@hermespilot/link 0.5.1 → 0.5.2

package/dist/cli/index.js

@@ -5,53 +5,1231 @@ import {
   LINK_VERSION,
   LinkHttpError,
   clearPairingClaim,
-  connectRelayControl,
+  createApp,
   createFileLogger,
-  currentCliScriptPath,
-  daemonLogFile,
+  createRotatingTextLogWriter,
   defaultLinkConfig,
   detectRuntimeEnvironment,
+  discoverRouteCandidates,
   ensureHermesApiServerAvailable,
   ensureHermesApiServerConfig,
   ensureIdentity,
-  getDaemonStatus,
+  getDaemonLogFile,
   getIdentityStatus,
   getLinkLogFile,
   hasActiveDevices,
   loadConfig,
   loadIdentity,
+  migrateLinkDatabase,
   normalizeLanHost,
   parseLogLevel,
   preparePairing,
-  probeLocalLinkService,
   readHermesApiServerConfig,
   readHermesVersion,
+  readJsonFile,
+  readLinkSystemInfo,
   readPairingClaim,
-  reportLinkStatusToServer,
   resolveHermesConfigPath,
   resolveHermesProfileDir,
   resolveRuntimePaths,
-  runDaemonSupervisor,
   saveConfig,
-  startDaemonProcess,
-  startLinkService,
-  stopDaemonProcess
-} from "../chunk-PULX22HX.js";
+  signIdentityPayload,
+  syncHermesLinkCronDeliveries,
+  writeJsonFile
+} from "../chunk-DZMN5RIV.js";
 
 // src/cli/index.ts
 import { Command } from "commander";
-import { realpathSync } from "fs";
-import path3 from "path";
+import { realpathSync as realpathSync2 } from "fs";
+import path5 from "path";
 import { createInterface } from "readline/promises";
 import { pathToFileURL } from "url";
 import qrcode from "qrcode-terminal";
 
 // src/autostart/autostart.ts
 import { execFile } from "child_process";
-import { mkdir, readFile, rm, writeFile } from "fs/promises";
+import { mkdir as mkdir3, readFile as readFile2, rm as rm3, writeFile as writeFile2 } from "fs/promises";
 import os from "os";
-import path from "path";
+import path2 from "path";
 import { promisify } from "util";
+
+// src/daemon/process.ts
+import { spawn } from "child_process";
+import { mkdir as mkdir2, readFile, rm as rm2 } from "fs/promises";
+import path from "path";
+
+// src/daemon/service.ts
+import { createServer } from "http";
+import { mkdir, rm, writeFile } from "fs/promises";
+
+// src/relay/control-client.ts
+import WebSocket from "ws";
+
+// src/relay/stream-policy.ts
+var DEFAULT_RELAY_STREAM_BATCH_POLICY = {
+  flushIntervalMs: 50,
+  flushBytes: 2 * 1024
+};
+var RELAY_STREAM_POLICY_CONSTRAINTS = {
+  flushIntervalMs: {
+    min: 50,
+    max: 1e3
+  },
+  flushBytes: {
+    min: 1024,
+    max: 64 * 1024
+  }
+};
+async function fetchRelayStreamBatchPolicy(serverBaseUrl, options = {}) {
+  const fetchImpl = options.fetchImpl ?? fetch;
+  const controller = new AbortController();
+  const timeout = setTimeout(() => controller.abort(), options.timeoutMs ?? 3e3);
+  timeout.unref?.();
+  try {
+    const response = await fetchImpl(`${serverBaseUrl.replace(/\/+$/u, "")}/api/v1/relay/stream-policy`, {
+      headers: {
+        accept: "application/json"
+      },
+      signal: controller.signal
+    });
+    if (!response.ok) {
+      return null;
+    }
+    const payload = await response.json().catch(() => null);
+    return readRelayStreamBatchPolicy(payload);
+  } catch {
+    return null;
+  } finally {
+    clearTimeout(timeout);
+  }
+}
+function readRelayStreamBatchPolicy(input) {
+  const record = readRecord(input);
+  const body = readRecord(record?.policy) ?? readRecord(record?.stream_batching) ?? record;
+  return normalizeRelayStreamBatchPolicy(body);
+}
+function normalizeRelayStreamBatchPolicy(input) {
+  const record = readRecord(input);
+  if (!record) {
+    return null;
+  }
+  const flushIntervalMs = readInteger(record.flushIntervalMs ?? record.flush_interval_ms);
+  const flushBytes = readInteger(record.flushBytes ?? record.flush_bytes);
+  if (flushIntervalMs === null || flushBytes === null || flushIntervalMs < RELAY_STREAM_POLICY_CONSTRAINTS.flushIntervalMs.min || flushIntervalMs > RELAY_STREAM_POLICY_CONSTRAINTS.flushIntervalMs.max || flushBytes < RELAY_STREAM_POLICY_CONSTRAINTS.flushBytes.min || flushBytes > RELAY_STREAM_POLICY_CONSTRAINTS.flushBytes.max) {
+    return null;
+  }
+  return {
+    flushIntervalMs,
+    flushBytes
+  };
+}
+function readRecord(value) {
+  return value && typeof value === "object" ? value : null;
+}
+function readInteger(value) {
+  return typeof value === "number" && Number.isInteger(value) ? value : null;
+}
+
+// src/relay/control-client.ts
+function connectRelayControl(options) {
+  const wsUrl = new URL(`${options.relayBaseUrl.replace(/\/+$/u, "")}/api/v1/relay/link/connect`);
+  wsUrl.protocol = wsUrl.protocol === "https:" ? "wss:" : "ws:";
+  wsUrl.searchParams.set("link_id", options.linkId);
+  const maxReconnectAttempts = options.maxReconnectAttempts ?? 5;
+  const backoffBaseMs = options.backoffBaseMs ?? 1e3;
+  const backoffMaxMs = options.backoffMaxMs ?? 3e4;
+  let reconnectAttempts = 0;
+  let closedByUser = false;
+  let socket = null;
+  let retryTimer = null;
+  let abortControllers = /* @__PURE__ */ new Map();
+  let fatalRelayRejection = null;
+  let latestNetworkRoutes = null;
+  const streamBatchPolicy = {
+    current: options.initialStreamBatchPolicy ?? DEFAULT_RELAY_STREAM_BATCH_POLICY,
+    onUpdate: options.onStreamBatchPolicy
+  };
+  const connect = () => {
+    options.onStatus?.({ state: "connecting", attempt: reconnectAttempts });
+    fatalRelayRejection = null;
+    socket = new WebSocket(wsUrl, {
+      headers: {
+        "x-hermes-link-version": LINK_VERSION
+      }
+    });
+    socket.on("open", () => {
+      reconnectAttempts = 0;
+      options.onStatus?.({ state: "connected", attempt: reconnectAttempts });
+      const currentSocket = socket;
+      if (currentSocket && latestNetworkRoutes) {
+        sendNetworkRoutes(currentSocket, options.linkId, latestNetworkRoutes);
+      }
+    });
+    socket.on("message", (raw) => {
+      if (!socket || typeof raw !== "string" && !Buffer.isBuffer(raw)) {
+        return;
+      }
+      void handleFrame(socket, String(raw), options.localPort, abortControllers, streamBatchPolicy).catch((error) => {
+        const message = error instanceof Error ? error.message : "Relay request failed";
+        socket?.send(JSON.stringify({ type: "http.error", id: "unknown", status: 502, message }));
+      });
+    });
+    socket.on("error", (error) => {
+      const message = error instanceof Error ? error.message : "Relay websocket error";
+      fatalRelayRejection = resolveFatalRelayRejection(message);
+      options.onStatus?.({
+        state: "disconnected",
+        attempt: reconnectAttempts,
+        message: fatalRelayRejection ?? message
+      });
+    });
+    socket.on("close", () => {
+      abortAll(abortControllers);
+      abortControllers = /* @__PURE__ */ new Map();
+      if (fatalRelayRejection) {
+        options.onStatus?.({
+          state: "failed",
+          attempt: reconnectAttempts,
+          message: fatalRelayRejection
+        });
+        return;
+      }
+      if (closedByUser) {
+        options.onStatus?.({ state: "disconnected", attempt: reconnectAttempts });
+        return;
+      }
+      if (reconnectAttempts >= maxReconnectAttempts) {
+        options.onStatus?.({ state: "failed", attempt: reconnectAttempts, message: "Relay reconnect attempts exhausted" });
+        return;
+      }
+      reconnectAttempts += 1;
+      const delay = computeBackoffMs(reconnectAttempts, backoffBaseMs, backoffMaxMs);
+      options.onStatus?.({ state: "retrying", attempt: reconnectAttempts, message: `Retrying in ${delay}ms` });
+      retryTimer = setTimeout(connect, delay);
+      retryTimer.unref?.();
+    });
+  };
+  connect();
+  return {
+    publishNetworkRoutes(routes) {
+      latestNetworkRoutes = routes;
+      if (socket?.readyState === WebSocket.OPEN) {
+        sendNetworkRoutes(socket, options.linkId, routes);
+      }
+    },
+    updateStreamBatchPolicy(policy) {
+      streamBatchPolicy.current = policy;
+      streamBatchPolicy.onUpdate?.(policy);
+    },
+    close() {
+      closedByUser = true;
+      if (retryTimer) {
+        clearTimeout(retryTimer);
+        retryTimer = null;
+      }
+      abortAll(abortControllers);
+      socket?.terminate();
+    }
+  };
+}
+function sendNetworkRoutes(socket, linkId, routes) {
+  socket.send(JSON.stringify({
+    type: "network.routes",
+    id: `routes_${Date.now().toString(36)}`,
+    payload: {
+      link_id: linkId,
+      lan_ips: routes.lanIps,
+      public_ipv4s: routes.publicIpv4s,
+      public_ipv6s: routes.publicIpv6s,
+      observed_at: (/* @__PURE__ */ new Date()).toISOString()
+    }
+  }));
+}
+function resolveFatalRelayRejection(message) {
+  if (!/Unexpected server response:\s*(400|401|403|426)\b/u.test(message)) {
+    return null;
+  }
+  return "Relay refused the Hermes Link connection. Check Link version and pairing state before retrying.";
+}
+function abortAll(abortControllers) {
+  for (const controller of abortControllers.values()) {
+    controller.abort();
+  }
+  abortControllers.clear();
+}
+function computeBackoffMs(attempt, baseMs, maxMs) {
+  const exponential = Math.min(maxMs, baseMs * 2 ** Math.max(0, attempt - 1));
+  const jitter = Math.floor(Math.random() * Math.min(1e3, exponential * 0.2));
+  return exponential + jitter;
+}
+async function handleFrame(socket, raw, localPort, abortControllers, streamBatchPolicy) {
+  const frame = JSON.parse(raw);
+  if (frame.type === "relay.config.update") {
+    const nextPolicy = readRelayStreamBatchPolicy(frame.payload);
+    if (nextPolicy) {
+      streamBatchPolicy.current = nextPolicy;
+      streamBatchPolicy.onUpdate?.(nextPolicy);
+    }
+    return;
+  }
+  if (frame.type === "http.cancel") {
+    abortControllers.get(frame.id)?.abort();
+    abortControllers.delete(frame.id);
+    return;
+  }
+  if (frame.type !== "http.request") {
+    return;
+  }
+  const abortController = new AbortController();
+  abortControllers.set(frame.id, abortController);
+  let sseBatcher = null;
+  try {
+    const response = await fetch(`http://127.0.0.1:${localPort}${frame.path}`, {
+      method: frame.method,
+      headers: frame.headers ?? {},
+      body: frame.bodyBase64 ? Buffer.from(frame.bodyBase64, "base64") : void 0,
+      signal: abortController.signal
+    });
+    const headers = Object.fromEntries(response.headers.entries());
+    const contentType = response.headers.get("content-type") ?? "";
+    if (response.body && contentType.includes("text/event-stream")) {
+      socket.send(JSON.stringify({ type: "http.stream.start", id: frame.id, status: response.status, headers }));
+      sseBatcher = createRelayStreamChunkBatcher(socket, frame.id, streamBatchPolicy);
+      const reader = response.body.getReader();
+      while (true) {
+        const next = await reader.read();
+        if (next.done) {
+          break;
+        }
+        sseBatcher.push(next.value);
+      }
+      sseBatcher.flush();
+      socket.send(JSON.stringify({ type: "http.stream.end", id: frame.id }));
+      return;
+    }
+    const body = Buffer.from(await response.arrayBuffer()).toString("base64");
+    socket.send(JSON.stringify({ type: "http.response", id: frame.id, status: response.status, headers, bodyBase64: body }));
+  } catch (error) {
+    if (abortController.signal.aborted || isAbortError(error)) {
+      return;
+    }
+    sseBatcher?.flush();
+    const message = error instanceof Error ? error.message : "Relay request failed";
+    socket.send(JSON.stringify({ type: "http.error", id: frame.id, status: 502, message }));
+  } finally {
+    sseBatcher?.dispose();
+    abortControllers.delete(frame.id);
+  }
+}
+function isAbortError(error) {
+  return typeof error === "object" && error !== null && "name" in error && error.name === "AbortError";
+}
+function createRelayStreamChunkBatcher(socket, id, streamBatchPolicy) {
+  let chunks = [];
+  let totalBytes = 0;
+  let flushTimer = null;
+  const clearFlushTimer = () => {
+    if (flushTimer == null) {
+      return;
+    }
+    clearTimeout(flushTimer);
+    flushTimer = null;
+  };
+  const flush = () => {
+    clearFlushTimer();
+    if (totalBytes <= 0) {
+      return;
+    }
+    const bodyBase64 = Buffer.concat(chunks, totalBytes).toString("base64");
+    chunks = [];
+    totalBytes = 0;
+    if (socket.readyState !== WebSocket.OPEN) {
+      return;
+    }
+    socket.send(JSON.stringify({ type: "http.stream.chunk", id, bodyBase64 }));
+  };
+  const scheduleFlush = () => {
+    if (flushTimer != null) {
+      return;
+    }
+    flushTimer = setTimeout(() => {
+      flushTimer = null;
+      flush();
+    }, streamBatchPolicy.current.flushIntervalMs);
+    flushTimer.unref?.();
+  };
+  return {
+    push(chunk) {
+      if (chunk.byteLength <= 0) {
+        return;
+      }
+      const buffer = Buffer.from(chunk);
+      chunks.push(buffer);
+      totalBytes += buffer.byteLength;
+      if (totalBytes >= streamBatchPolicy.current.flushBytes) {
+        flush();
+        return;
+      }
+      scheduleFlush();
+    },
+    flush,
+    dispose() {
+      clearFlushTimer();
+      chunks = [];
+      totalBytes = 0;
+    }
+  };
+}
+
+// src/link/network-report-state.ts
+var DEFAULT_AUTO_DAILY_LIMIT = 20;
+async function readNetworkReportState(paths) {
+  const state = await readLinkState(paths);
+  return normalizeNetworkReportState(state.networkReport);
+}
+async function markNetworkStatusReported(paths, snapshotInput, reportedAt = /* @__PURE__ */ new Date()) {
+  const snapshot = normalizeNetworkSnapshot(snapshotInput);
+  await updateNetworkReportState(paths, (current) => ({
+    ...current,
+    lastReportedLanIps: snapshot.lanIps,
+    lastReportedPublicIpv4s: snapshot.publicIpv4s,
+    lastReportedPublicIpv6s: snapshot.publicIpv6s,
+    lastReportedAt: reportedAt.toISOString(),
+    lastAutoAttempt: current.lastAutoAttempt ? { ...current.lastAutoAttempt, ...snapshot, success: true } : null
+  }));
+}
+async function reserveAutomaticNetworkReport(paths, snapshotInput, options = {}) {
+  const snapshot = normalizeNetworkSnapshot(snapshotInput);
+  const now = options.now ?? /* @__PURE__ */ new Date();
+  const dailyLimit = Math.max(0, Math.floor(options.dailyLimit ?? DEFAULT_AUTO_DAILY_LIMIT));
+  let reservation = { allowed: false, reason: "unchanged" };
+  await updateNetworkReportState(paths, (current) => {
+    if (sameNetworkSnapshot(readReportedSnapshot(current), snapshot)) {
+      const lastReportedAt = current.lastReportedAt ? Date.parse(current.lastReportedAt) : Number.NaN;
+      const unchangedMinIntervalMs = Math.max(0, Math.floor(options.unchangedMinIntervalMs ?? 0));
+      if (!options.force || Number.isFinite(lastReportedAt) && now.getTime() - lastReportedAt < unchangedMinIntervalMs) {
+        reservation = { allowed: false, reason: "unchanged" };
+        return current;
+      }
+    }
+    if (current.lastAutoAttempt && !current.lastAutoAttempt.success && sameNetworkSnapshot(readAttemptSnapshot(current.lastAutoAttempt), snapshot)) {
+      reservation = { allowed: false, reason: "failed_snapshot_not_retried" };
+      return current;
+    }
+    const quotaDay = formatUtcDay(now);
+    const reportsToday = current.autoQuotaDay === quotaDay ? current.autoReportsToday : 0;
+    if (reportsToday >= dailyLimit) {
+      reservation = { allowed: false, reason: "daily_limit_reached" };
+      return current;
+    }
+    reservation = { allowed: true };
+    return {
+      ...current,
+      autoQuotaDay: quotaDay,
+      autoReportsToday: reportsToday + 1,
+      lastAutoAttempt: {
+        ...snapshot,
+        attemptedAt: now.toISOString(),
+        success: false
+      }
+    };
+  });
+  return reservation;
+}
+async function mergeLastReportedPublicRoutes(paths, snapshotInput) {
+  const state = await readNetworkReportState(paths);
+  return {
+    ...snapshotInput,
+    publicIpv4s: uniqueStrings([
+      ...snapshotInput.publicIpv4s,
+      ...state.lastReportedPublicIpv4s
+    ]).slice(0, 2),
+    publicIpv6s: uniqueStrings([
+      ...snapshotInput.publicIpv6s,
+      ...state.lastReportedPublicIpv6s
+    ]).slice(0, 2)
+  };
+}
+async function updateNetworkReportState(paths, update) {
+  const state = await readLinkState(paths);
+  const next = {
+    ...state,
+    networkReport: update(normalizeNetworkReportState(state.networkReport))
+  };
+  await writeJsonFile(paths.stateFile, next);
+}
+async function readLinkState(paths) {
+  const state = await readJsonFile(paths.stateFile);
+  return state && typeof state === "object" ? state : {};
+}
+function normalizeNetworkReportState(value) {
+  const record = value && typeof value === "object" ? value : {};
+  return {
+    lastReportedLanIps: normalizeLanIps(record.lastReportedLanIps),
+    lastReportedPublicIpv4s: normalizeLanIps(record.lastReportedPublicIpv4s),
+    lastReportedPublicIpv6s: normalizeLanIps(record.lastReportedPublicIpv6s),
+    lastReportedAt: typeof record.lastReportedAt === "string" ? record.lastReportedAt : null,
+    autoQuotaDay: typeof record.autoQuotaDay === "string" ? record.autoQuotaDay : null,
+    autoReportsToday: Number.isFinite(record.autoReportsToday) ? Math.max(0, Math.floor(record.autoReportsToday ?? 0)) : 0,
+    lastAutoAttempt: normalizeAttempt(record.lastAutoAttempt)
+  };
+}
+function normalizeAttempt(value) {
+  if (!value || typeof value !== "object") {
+    return null;
+  }
+  const record = value;
+  if (typeof record.attemptedAt !== "string") {
+    return null;
+  }
+  return {
+    lanIps: normalizeLanIps(record.lanIps),
+    publicIpv4s: normalizeLanIps(record.publicIpv4s),
+    publicIpv6s: normalizeLanIps(record.publicIpv6s),
+    attemptedAt: record.attemptedAt,
+    success: record.success === true
+  };
+}
+function normalizeNetworkSnapshot(value) {
+  if (Array.isArray(value)) {
+    return {
+      lanIps: normalizeLanIps(value),
+      publicIpv4s: [],
+      publicIpv6s: []
+    };
+  }
+  const record = value && typeof value === "object" ? value : {};
+  return {
+    lanIps: normalizeLanIps(record.lanIps),
+    publicIpv4s: normalizeLanIps(record.publicIpv4s),
+    publicIpv6s: normalizeLanIps(record.publicIpv6s)
+  };
+}
+function readReportedSnapshot(state) {
+  return {
+    lanIps: state.lastReportedLanIps,
+    publicIpv4s: state.lastReportedPublicIpv4s,
+    publicIpv6s: state.lastReportedPublicIpv6s
+  };
+}
+function readAttemptSnapshot(attempt) {
+  return {
+    lanIps: attempt.lanIps,
+    publicIpv4s: attempt.publicIpv4s,
+    publicIpv6s: attempt.publicIpv6s
+  };
+}
+function normalizeLanIps(value) {
+  if (!Array.isArray(value)) {
+    return [];
+  }
+  return [
+    ...new Set(
+      value.filter((item) => typeof item === "string" && item.trim().length > 0).map((item) => item.trim())
+    )
+  ];
+}
+function sameNetworkSnapshot(left, right) {
+  return sameStringList(left.lanIps, right.lanIps) && sameStringList(left.publicIpv4s, right.publicIpv4s) && sameStringList(left.publicIpv6s, right.publicIpv6s);
+}
+function sameStringList(left, right) {
+  if (left.length !== right.length) {
+    return false;
+  }
+  return left.every((value, index) => value === right[index]);
+}
+function uniqueStrings(values) {
+  return [...new Set(values)];
+}
+function formatUtcDay(date) {
+  return date.toISOString().slice(0, 10);
+}
+
+// src/link/server-report.ts
+async function reportLinkStatusToServer(options = {}) {
+  const paths = options.paths ?? resolveRuntimePaths();
+  const [identity, config] = await Promise.all([loadIdentity(paths), loadConfig(paths)]);
+  if (!identity?.link_id) {
+    return null;
+  }
+  const discoveredRoutes = options.routes ?? await discoverRouteCandidates({
+    port: config.port,
+    relayBaseUrl: config.relayBaseUrl,
+    linkId: identity.link_id,
+    installId: identity.install_id,
+    publicKeyPem: identity.public_key_pem,
+    observePublicRoute: true,
+    configuredLanHost: config.lanHost,
+    fetchImpl: options.fetchImpl
+  });
+  const routes = await mergeLastReportedPublicRoutes(paths, discoveredRoutes);
+  const systemInfo = readLinkSystemInfo();
+  const payload = {
+    type: "hermes_link_status_report",
+    link_id: identity.link_id,
+    install_id: identity.install_id,
+    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,
+    reported_at: (/* @__PURE__ */ new Date()).toISOString()
+  };
+  const signature = signIdentityPayload(identity, canonicalJson(payload));
+  const fetcher = options.fetchImpl ?? fetch;
+  const response = await fetcher(
+    `${config.serverBaseUrl.replace(/\/+$/u, "")}/api/v1/links/${encodeURIComponent(identity.link_id)}/report`,
+    {
+      method: "POST",
+      headers: {
+        accept: "application/json",
+        "content-type": "application/json"
+      },
+      body: JSON.stringify({
+        ...payload,
+        public_key_pem: identity.public_key_pem,
+        signature
+      })
+    }
+  );
+  const body = await response.json().catch(() => null);
+  if (!response.ok || !body) {
+    const message = readErrorMessage(body) ?? `HermesPilot Server request failed with HTTP ${response.status}`;
+    throw new LinkHttpError(response.status, "server_request_failed", message);
+  }
+  await markNetworkStatusReported(paths, routes);
+  return body;
+}
+function canonicalJson(value) {
+  return JSON.stringify(sortJsonValue(value));
+}
+function sortJsonValue(value) {
+  if (Array.isArray(value)) {
+    return value.map(sortJsonValue);
+  }
+  if (value && typeof value === "object") {
+    const record = value;
+    const sorted = {};
+    for (const key of Object.keys(record).sort()) {
+      sorted[key] = sortJsonValue(record[key]);
+    }
+    return sorted;
+  }
+  return value;
+}
+function readErrorMessage(payload) {
+  if (typeof payload !== "object" || payload === null) {
+    return null;
+  }
+  const error = payload.error;
+  if (typeof error !== "object" || error === null) {
+    return null;
+  }
+  const message = error.message;
+  return typeof message === "string" ? message : null;
+}
+
+// src/daemon/lan-ip-monitor.ts
+var DEFAULT_INTERVAL_MS = 5 * 6e4;
+var DEFAULT_DAILY_REPORT_LIMIT = 20;
+var DEFAULT_STARTUP_REPORT_MIN_INTERVAL_MS = 15 * 6e4;
+function startLanIpMonitor(options) {
+  let running = false;
+  let closed = false;
+  let current = Promise.resolve();
+  const check = async (context = {}) => {
+    if (running || closed) {
+      return;
+    }
+    running = true;
+    try {
+      await checkLanIpChange(options, context);
+    } catch (error) {
+      void options.logger.warn("lan_ip_monitor_failed", {
+        error: error instanceof Error ? error.message : String(error)
+      });
+    } finally {
+      running = false;
+    }
+  };
+  current = check({ forceReport: true, publishToRelay: true, observePublicRoute: true });
+  const timer = setInterval(() => {
+    current = check({ observePublicRoute: false });
+  }, options.intervalMs ?? DEFAULT_INTERVAL_MS);
+  timer.unref?.();
+  return {
+    async refreshPublicRoutes() {
+      current = check({ forceReport: true, publishToRelay: true, observePublicRoute: true });
+      await current;
+    },
+    async close() {
+      closed = true;
+      clearInterval(timer);
+      await current.catch(() => void 0);
+    }
+  };
+}
+async function checkLanIpChange(options, context = {}) {
+  const [identity, config] = await Promise.all([
+    loadIdentity(options.paths),
+    loadConfig(options.paths)
+  ]);
+  if (!identity?.link_id) {
+    return;
+  }
+  const discoveredRoutes = await discoverRouteCandidates({
+    port: config.port,
+    relayBaseUrl: config.relayBaseUrl,
+    linkId: identity.link_id,
+    installId: identity.install_id,
+    publicKeyPem: identity.public_key_pem,
+    observePublicRoute: context.observePublicRoute === true,
+    configuredLanHost: config.lanHost,
+    fetchImpl: options.fetchImpl
+  });
+  const routes = await mergeLastReportedPublicRoutes(options.paths, discoveredRoutes);
+  if (context.publishToRelay) {
+    options.onNetworkRoutes?.(routes);
+  }
+  const reservation = await reserveAutomaticNetworkReport(options.paths, routes, {
+    dailyLimit: options.dailyReportLimit ?? DEFAULT_DAILY_REPORT_LIMIT,
+    force: context.forceReport === true,
+    unchangedMinIntervalMs: options.startupReportMinIntervalMs ?? DEFAULT_STARTUP_REPORT_MIN_INTERVAL_MS
+  });
+  if (!reservation.allowed) {
+    const logFields = {
+      lan_ips: routes.lanIps,
+      public_ipv4s: routes.publicIpv4s,
+      public_ipv6s: routes.publicIpv6s,
+      reason: reservation.reason
+    };
+    void options.logger.debug("lan_ip_report_skipped", logFields);
+    return;
+  }
+  try {
+    const result = await reportLinkStatusToServer({
+      paths: options.paths,
+      fetchImpl: options.fetchImpl,
+      routes
+    });
+    if (result) {
+      options.onNetworkRoutes?.(routes);
+      void options.logger.info("lan_ip_change_reported", {
+        link_id: result.linkId,
+        lan_ips: routes.lanIps,
+        public_ipv4s: routes.publicIpv4s,
+        public_ipv6s: routes.publicIpv6s
+      });
+    }
+  } catch (error) {
+    void options.logger.warn("lan_ip_change_report_failed", {
+      lan_ips: routes.lanIps,
+      error: error instanceof Error ? error.message : String(error)
+    });
+  }
+}
+
+// src/daemon/scheduler.ts
+function startCronDeliveryScheduler(options) {
+  let running = false;
+  let current = Promise.resolve();
+  const syncCronDeliveries = async () => {
+    if (running) {
+      return;
+    }
+    running = true;
+    try {
+      await syncHermesLinkCronDeliveries(
+        options.paths,
+        options.conversations,
+        options.logger
+      );
+    } catch (error) {
+      void options.logger.warn("cron_link_delivery_sync_failed", {
+        source: "daemon_scheduler",
+        error: error instanceof Error ? error.message : String(error)
+      });
+    } finally {
+      running = false;
+    }
+  };
+  const timer = setInterval(() => {
+    current = syncCronDeliveries();
+  }, options.intervalMs ?? 3e4);
+  timer.unref?.();
+  return {
+    async close() {
+      clearInterval(timer);
+      await current.catch(() => void 0);
+    }
+  };
+}
+function startHermesSessionSyncScheduler(options) {
+  let running = false;
+  let current = Promise.resolve();
+  const syncSessions = async () => {
+    if (running) {
+      return;
+    }
+    running = true;
+    try {
+      await options.conversations.syncHermesSessions();
+    } catch (error) {
+      void options.logger.warn("hermes_session_sync_failed", {
+        source: "daemon_scheduler",
+        error: error instanceof Error ? error.message : String(error)
+      });
+    } finally {
+      running = false;
+    }
+  };
+  const timer = setInterval(() => {
+    current = syncSessions();
+  }, options.intervalMs ?? 10 * 60 * 1e3);
+  timer.unref?.();
+  return {
+    async close() {
+      clearInterval(timer);
+      await current.catch(() => void 0);
+    }
+  };
+}
+
+// src/daemon/service.ts
+var DEFAULT_RELAY_READY_TIMEOUT_MS = 2e3;
+var RELAY_RECONNECT_PUBLIC_ROUTE_REFRESH_MIN_INTERVAL_MS = 15 * 6e4;
+async function startLinkService(options = {}) {
+  const paths = options.paths ?? resolveRuntimePaths();
+  const [identity, config] = await Promise.all([loadIdentity(paths), loadConfig(paths)]);
+  const logger = createFileLogger({ paths, minLevel: config.logLevel });
+  await logger.info("service_starting", {
+    port: config.port,
+    mode: identity?.link_id ? "paired" : "local-only"
+  });
+  const migration = await migrateLinkDatabase(paths);
+  if (migration.appliedVersions.length > 0) {
+    await logger.info("database_migrated", {
+      database_file: migration.databaseFile,
+      applied_versions: migration.appliedVersions,
+      current_version: migration.currentVersion
+    });
+  }
+  const conversations = new ConversationService(paths, logger);
+  await conversations.rebuildStatisticsIndex();
+  let relay = null;
+  let lanIpMonitor = null;
+  const loadRelayStreamBatchPolicy = async (source) => {
+    const streamBatchPolicy = await fetchRelayStreamBatchPolicy(config.serverBaseUrl);
+    if (!streamBatchPolicy) {
+      return null;
+    }
+    relay?.updateStreamBatchPolicy(streamBatchPolicy);
+    void logger.info("relay_stream_policy_loaded", {
+      source,
+      flushIntervalMs: streamBatchPolicy.flushIntervalMs,
+      flushBytes: streamBatchPolicy.flushBytes
+    });
+    return streamBatchPolicy;
+  };
+  let hermesSessionSync = Promise.resolve();
+  const triggerHermesSessionSync = () => {
+    hermesSessionSync = Promise.resolve().then(() => conversations.syncHermesSessions()).then(() => void 0).catch((error) => {
+      void logger.warn("hermes_session_sync_failed", {
+        source: "service_startup",
+        error: error instanceof Error ? error.message : String(error)
+      });
+    });
+  };
+  const app = await createApp({
+    paths,
+    logger,
+    conversations,
+    onPairingClaimed: async () => {
+      triggerHermesSessionSync();
+      void loadRelayStreamBatchPolicy("pairing_claimed");
+      await options.onPairingClaimed?.();
+    }
+  });
+  const server = createServer(app.callback());
+  try {
+    await listenServer(server, config.port);
+  } catch (error) {
+    await logger.error("service_start_failed", {
+      port: config.port,
+      link_id: identity?.link_id ?? null,
+      error: error instanceof Error ? error.message : String(error)
+    });
+    await logger.flush();
+    throw error;
+  }
+  server.on("error", (error) => {
+    void logger.error("service_error", {
+      port: config.port,
+      link_id: identity?.link_id ?? null,
+      error: error.message
+    });
+  });
+  void logger.info("service_started", {
+    port: config.port,
+    link_id: identity?.link_id ?? null
+  });
+  triggerHermesSessionSync();
+  const scheduler = startCronDeliveryScheduler({
+    paths,
+    conversations,
+    logger
+  });
+  const hermesSessionSyncScheduler = startHermesSessionSyncScheduler({
+    conversations,
+    logger
+  });
+  let hasSeenRelayConnected = false;
+  let lastRelayReconnectPublicRouteRefreshAt = 0;
+  if (identity?.link_id) {
+    let resolveRelayReady = null;
+    const relayReady = new Promise((resolve) => {
+      resolveRelayReady = resolve;
+    });
+    relay = connectRelayControl({
+      relayBaseUrl: config.relayBaseUrl,
+      linkId: identity.link_id,
+      localPort: config.port,
+      maxReconnectAttempts: options.relayMaxReconnectAttempts ?? 5,
+      backoffBaseMs: 1e3,
+      backoffMaxMs: 3e4,
+      onStreamBatchPolicy: (policy) => {
+        void logger.info("relay_stream_policy_updated", {
+          flushIntervalMs: policy.flushIntervalMs,
+          flushBytes: policy.flushBytes
+        });
+      },
+      onStatus: (status) => {
+        void logger.info("relay_status", status);
+        if (status.state === "connected") {
+          const now = Date.now();
+          if (hasSeenRelayConnected && lanIpMonitor && now - lastRelayReconnectPublicRouteRefreshAt >= RELAY_RECONNECT_PUBLIC_ROUTE_REFRESH_MIN_INTERVAL_MS) {
+            lastRelayReconnectPublicRouteRefreshAt = now;
+            void lanIpMonitor.refreshPublicRoutes();
+          }
+          hasSeenRelayConnected = true;
+          resolveRelayReady?.(true);
+          resolveRelayReady = null;
+        } else if (status.state === "failed") {
+          resolveRelayReady?.(false);
+          resolveRelayReady = null;
+        }
+      }
+    });
+    void loadRelayStreamBatchPolicy("service_startup");
+    if (options.waitForRelayReady) {
+      await Promise.race([
+        relayReady,
+        waitForRelayReadyTimeout(options.relayReadyTimeoutMs)
+      ]);
+      resolveRelayReady = null;
+    }
+  } else {
+    void logger.info("relay_skipped", { reason: "link_not_paired" });
+  }
+  lanIpMonitor = startLanIpMonitor({
+    paths,
+    logger,
+    intervalMs: options.lanIpMonitorIntervalMs,
+    dailyReportLimit: options.lanIpMonitorDailyReportLimit,
+    fetchImpl: options.lanIpMonitorFetchImpl,
+    onNetworkRoutes: (routes) => {
+      relay?.publishNetworkRoutes(routes);
+    }
+  });
+  if (options.writePidFile) {
+    await writePidFile(paths);
+  }
+  return {
+    async close() {
+      relay?.close();
+      await closeServer(server);
+      await Promise.all([
+        scheduler.close(),
+        hermesSessionSyncScheduler.close(),
+        lanIpMonitor?.close(),
+        hermesSessionSync.catch(() => void 0)
+      ]);
+      await logger.info("service_stopped");
+      await logger.flush();
+      if (options.writePidFile) {
+        await rm(pidFilePath(paths), { force: true }).catch(() => void 0);
+      }
+    }
+  };
+}
+function waitForRelayReadyTimeout(timeoutMs) {
+  return new Promise((resolve) => {
+    const timer = setTimeout(
+      () => resolve(false),
+      timeoutMs ?? DEFAULT_RELAY_READY_TIMEOUT_MS
+    );
+    timer.unref?.();
+  });
+}
+function pidFilePath(paths = resolveRuntimePaths()) {
+  return `${paths.runDir}/hermeslink.pid`;
+}
+async function writePidFile(paths) {
+  await mkdir(paths.runDir, { recursive: true, mode: 448 });
+  await writeFile(pidFilePath(paths), `${process.pid}
+`, { mode: 384 });
+}
+async function closeServer(server) {
+  await new Promise((resolve, reject) => {
+    let settled = false;
+    let forceCloseTimer;
+    let timeoutTimer;
+    const settle = (error) => {
+      if (settled) {
+        return;
+      }
+      settled = true;
+      clearTimeout(forceCloseTimer);
+      clearTimeout(timeoutTimer);
+      if (error) {
+        reject(error);
+        return;
+      }
+      resolve();
+    };
+    forceCloseTimer = setTimeout(() => {
+      server.closeIdleConnections?.();
+      server.closeAllConnections?.();
+    }, 250);
+    timeoutTimer = setTimeout(() => {
+      server.closeAllConnections?.();
+      settle();
+    }, 5e3);
+    server.close((error) => {
+      if (error) {
+        settle(error);
+        return;
+      }
+      settle();
+    });
+    server.closeIdleConnections?.();
+  });
+}
+async function listenServer(server, port) {
+  await new Promise((resolve, reject) => {
+    const cleanup = () => {
+      server.off("error", onError);
+      server.off("listening", onListening);
+    };
+    const onError = (error) => {
+      cleanup();
+      reject(error);
+    };
+    const onListening = () => {
+      cleanup();
+      resolve();
+    };
+    server.once("error", onError);
+    server.once("listening", onListening);
+    server.listen(port);
+  });
+}
+
+// src/daemon/process.ts
+async function startDaemonProcess(paths = resolveRuntimePaths()) {
+  const config = await loadConfig(paths);
+  let status = await getDaemonStatus(paths);
+  if (status.running) {
+    const probe = await probeLocalLinkService({ port: config.port, timeoutMs: 500 });
+    if (probe.reachable) {
+      return status;
+    }
+    await stopDaemonProcess(paths);
+    status = await getDaemonStatus(paths);
+    if (status.running) {
+      return status;
+    }
+  }
+  await mkdir2(paths.logsDir, { recursive: true, mode: 448 });
+  await mkdir2(paths.runDir, { recursive: true, mode: 448 });
+  const scriptPath = currentCliScriptPath();
+  const child = spawn(process.execPath, [scriptPath, "daemon-supervisor"], {
+    detached: true,
+    stdio: "ignore",
+    env: process.env
+  });
+  child.unref();
+  for (let index = 0; index < 12; index += 1) {
+    await wait(250);
+    const next = await getDaemonStatus(paths);
+    if (next.running && (await probeLocalLinkService({ port: config.port, timeoutMs: 500 })).reachable) {
+      return next;
+    }
+  }
+  return await getDaemonStatus(paths);
+}
+async function runDaemonSupervisor(paths = resolveRuntimePaths()) {
+  await mkdir2(paths.logsDir, { recursive: true, mode: 448 });
+  const log = createRotatingTextLogWriter({
+    paths,
+    fileName: path.basename(daemonLogFile(paths))
+  });
+  const scriptPath = currentCliScriptPath();
+  const child = spawn(process.execPath, [scriptPath, "daemon", "--foreground"], {
+    stdio: ["ignore", "pipe", "pipe"],
+    env: process.env
+  });
+  const write = (chunk) => {
+    void log.write(chunk);
+  };
+  write(`[${(/* @__PURE__ */ new Date()).toISOString()}] daemon supervisor started
+`);
+  child.stdout?.on("data", write);
+  child.stderr?.on("data", write);
+  const forwardStop = () => {
+    if (child.pid && isProcessAlive(child.pid)) {
+      child.kill("SIGTERM");
+    }
+  };
+  process.once("SIGINT", forwardStop);
+  process.once("SIGTERM", forwardStop);
+  const result = await new Promise((resolve, reject) => {
+    child.once("error", reject);
+    child.once("exit", (code, signal) => resolve({ code, signal }));
+  }).catch((error) => {
+    write(`[${(/* @__PURE__ */ new Date()).toISOString()}] daemon supervisor failed: ${error instanceof Error ? error.message : String(error)}
+`);
+    return { code: 1, signal: null };
+  });
+  process.off("SIGINT", forwardStop);
+  process.off("SIGTERM", forwardStop);
+  write(
+    `[${(/* @__PURE__ */ new Date()).toISOString()}] daemon supervisor stopped code=${result.code ?? "null"} signal=${result.signal ?? "null"}
+`
+  );
+  await log.flush();
+  return result.code ?? (result.signal ? 0 : 1);
+}
+async function probeLocalLinkService(options) {
+  const unreachable = {
+    reachable: false,
+    reusable: false,
+    linkId: null,
+    version: null
+  };
+  let response;
+  try {
+    response = await fetch(`http://127.0.0.1:${options.port}/api/v1/bootstrap`, {
+      headers: { accept: "application/json" },
+      signal: AbortSignal.timeout(options.timeoutMs ?? 1e3)
+    });
+  } catch {
+    return unreachable;
+  }
+  if (!response.ok) {
+    return unreachable;
+  }
+  const payload = await response.json().catch(() => null);
+  if (!payload || payload.api_version !== 1) {
+    return unreachable;
+  }
+  const linkId = typeof payload.link_id === "string" ? payload.link_id : null;
+  return {
+    reachable: true,
+    reusable: options.linkId ? linkId === options.linkId : true,
+    linkId,
+    version: typeof payload.version === "string" ? payload.version : null
+  };
+}
+async function stopDaemonProcess(paths = resolveRuntimePaths()) {
+  const status = await getDaemonStatus(paths);
+  if (!status.running || !status.pid) {
+    return status;
+  }
+  try {
+    process.kill(status.pid, "SIGTERM");
+  } catch {
+    await rm2(pidFilePath(paths), { force: true }).catch(() => void 0);
+    return await getDaemonStatus(paths);
+  }
+  for (let index = 0; index < 20; index += 1) {
+    await wait(250);
+    if (!isProcessAlive(status.pid)) {
+      break;
+    }
+  }
+  if (isProcessAlive(status.pid)) {
+    try {
+      process.kill(status.pid, "SIGKILL");
+    } catch {
+    }
+    for (let index = 0; index < 10; index += 1) {
+      await wait(250);
+      if (!isProcessAlive(status.pid)) {
+        break;
+      }
+    }
+  }
+  if (!isProcessAlive(status.pid) || !await pidBackedServiceIsReachable(paths)) {
+    await rm2(pidFilePath(paths), { force: true }).catch(() => void 0);
+  }
+  return await getDaemonStatus(paths);
+}
+async function getDaemonStatus(paths = resolveRuntimePaths()) {
+  const pidFile = pidFilePath(paths);
+  const pid = await readPid(pidFile);
+  if (pid && !isProcessAlive(pid)) {
+    await rm2(pidFile, { force: true }).catch(() => void 0);
+    return {
+      running: false,
+      pid: null,
+      pidFile,
+      logFile: daemonLogFile(paths)
+    };
+  }
+  return {
+    running: Boolean(pid),
+    pid,
+    pidFile,
+    logFile: daemonLogFile(paths)
+  };
+}
+function daemonLogFile(paths = resolveRuntimePaths()) {
+  return getDaemonLogFile(paths);
+}
+function currentCliScriptPath() {
+  return process.argv[1];
+}
+async function readPid(filePath) {
+  const raw = await readFile(filePath, "utf8").catch(() => null);
+  if (!raw) {
+    return null;
+  }
+  const pid = Number.parseInt(raw.trim(), 10);
+  return Number.isInteger(pid) && pid > 0 ? pid : null;
+}
+function isProcessAlive(pid) {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch {
+    return false;
+  }
+}
+async function pidBackedServiceIsReachable(paths) {
+  const config = await loadConfig(paths).catch(() => null);
+  if (!config) {
+    return false;
+  }
+  return (await probeLocalLinkService({ port: config.port, timeoutMs: 500 })).reachable;
+}
+function wait(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+// src/autostart/autostart.ts
 var execFileAsync = promisify(execFile);
 var MACOS_LABEL = "com.hermespilot.link";
 async function enableAutostart() {
@@ -59,14 +1237,14 @@ async function enableAutostart() {
   if (!definition) {
     return unsupportedStatus();
   }
-  await mkdir(path.dirname(definition.filePath), { recursive: true, mode: 448 });
-  await writeFile(definition.filePath, definition.content, { mode: 384 });
+  await mkdir3(path2.dirname(definition.filePath), { recursive: true, mode: 448 });
+  await writeFile2(definition.filePath, definition.content, { mode: 384 });
   if (definition.method === "systemd-user") {
-    await execFileAsync("systemctl", ["--user", "enable", path.basename(definition.filePath)]).catch(async () => {
-      await rm(definition.filePath, { force: true }).catch(() => void 0);
+    await execFileAsync("systemctl", ["--user", "enable", path2.basename(definition.filePath)]).catch(async () => {
+      await rm3(definition.filePath, { force: true }).catch(() => void 0);
       const fallback = xdgAutostartDefinition();
-      await mkdir(path.dirname(fallback.filePath), { recursive: true, mode: 448 });
-      await writeFile(fallback.filePath, fallback.content, { mode: 384 });
+      await mkdir3(path2.dirname(fallback.filePath), { recursive: true, mode: 448 });
+      await writeFile2(fallback.filePath, fallback.content, { mode: 384 });
     });
   }
   return await getAutostartStatus();
@@ -75,9 +1253,9 @@ async function disableAutostart() {
   const definitions = await allAutostartDefinitions();
   for (const definition of definitions) {
     if (definition.method === "systemd-user") {
-      await execFileAsync("systemctl", ["--user", "disable", path.basename(definition.filePath)]).catch(() => void 0);
+      await execFileAsync("systemctl", ["--user", "disable", path2.basename(definition.filePath)]).catch(() => void 0);
     }
-    await rm(definition.filePath, { force: true }).catch(() => void 0);
+    await rm3(definition.filePath, { force: true }).catch(() => void 0);
   }
   return await getAutostartStatus();
 }
@@ -87,7 +1265,7 @@ async function getAutostartStatus() {
     return unsupportedStatus();
   }
   for (const definition of definitions) {
-    const content = await readFile(definition.filePath, "utf8").catch(() => null);
+    const content = await readFile2(definition.filePath, "utf8").catch(() => null);
     if (content !== null) {
       return {
         supported: true,
@@ -138,7 +1316,8 @@ async function hasSystemctlUser() {
   }
 }
 function launchdDefinition() {
-  const filePath = path.join(os.homedir(), "Library", "LaunchAgents", `${MACOS_LABEL}.plist`);
+  const filePath = path2.join(os.homedir(), "Library", "LaunchAgents", `${MACOS_LABEL}.plist`);
+  const environment = autostartEnvironment();
   return {
     method: "launchd",
     filePath,
@@ -154,6 +1333,10 @@ function launchdDefinition() {
     <string>${xmlEscape(currentCliScriptPath())}</string>
     <string>daemon-supervisor</string>
   </array>
+  <key>EnvironmentVariables</key>
+  <dict>
+${plistEnvironmentEntries(environment)}
+  </dict>
   <key>RunAtLoad</key>
   <true/>
   <key>KeepAlive</key>
@@ -164,7 +1347,8 @@ function launchdDefinition() {
   };
 }
 function systemdUserDefinition() {
-  const filePath = path.join(os.homedir(), ".config", "systemd", "user", "hermeslink.service");
+  const filePath = path2.join(os.homedir(), ".config", "systemd", "user", "hermeslink.service");
+  const environment = autostartEnvironment();
   return {
     method: "systemd-user",
     filePath,
@@ -174,6 +1358,7 @@ After=network-online.target
 
 [Service]
 Type=simple
+${systemdEnvironmentLines(environment)}
 ExecStart=${systemdQuote(process.execPath)} ${systemdQuote(currentCliScriptPath())} daemon-supervisor
 Restart=no
 
@@ -183,28 +1368,33 @@ WantedBy=default.target
   };
 }
 function xdgAutostartDefinition() {
-  const filePath = path.join(os.homedir(), ".config", "autostart", "hermeslink.desktop");
+  const filePath = path2.join(os.homedir(), ".config", "autostart", "hermeslink.desktop");
+  const environment = autostartEnvironment();
   return {
     method: "xdg-autostart",
     filePath,
     content: `[Desktop Entry]
 Type=Application
 Name=Hermes Link
-Exec=${desktopQuote(process.execPath)} ${desktopQuote(currentCliScriptPath())} daemon-supervisor
+Exec=${desktopQuote("/usr/bin/env")} ${desktopEnvironmentArgs(environment)} ${desktopQuote(process.execPath)} ${desktopQuote(currentCliScriptPath())} daemon-supervisor
 Terminal=false
 X-GNOME-Autostart-enabled=true
 `
   };
 }
 function windowsStartupDefinition() {
-  const appData = process.env.APPDATA ?? path.join(os.homedir(), "AppData", "Roaming");
-  const filePath = path.join(appData, "Microsoft", "Windows", "Start Menu", "Programs", "Startup", "HermesLink.cmd");
+  const appData = process.env.APPDATA ?? path2.join(os.homedir(), "AppData", "Roaming");
+  const filePath = path2.join(appData, "Microsoft", "Windows", "Start Menu", "Programs", "Startup", "HermesLink.cmd");
+  const environment = autostartEnvironment();
   return {
     method: "windows-startup",
     filePath,
-    content: `@echo off\r
-start "" /min "${process.execPath}" "${currentCliScriptPath()}" daemon-supervisor\r
-`
+    content: [
+      "@echo off",
+      ...cmdEnvironmentLines(environment),
+      `start "" /min "${process.execPath}" "${currentCliScriptPath()}" daemon-supervisor`,
+      ""
+    ].join("\r\n")
   };
 }
 function unsupportedStatus() {
@@ -224,6 +1414,57 @@ function systemdQuote(value) {
 function desktopQuote(value) {
   return `"${value.replaceAll("\\", "\\\\").replaceAll('"', '\\"')}"`;
 }
+function autostartEnvironment() {
+  const environment = {};
+  const pathValue = buildAutostartPath();
+  if (pathValue) {
+    environment.PATH = pathValue;
+  }
+  const hermesBin = process.env.HERMES_BIN?.trim();
+  if (hermesBin) {
+    environment.HERMES_BIN = hermesBin;
+  }
+  return environment;
+}
+function buildAutostartPath() {
+  const separator = process.platform === "win32" ? ";" : ":";
+  const candidates = [
+    path2.dirname(process.execPath),
+    ...(process.env.PATH ?? "").split(separator),
+    path2.join(os.homedir(), ".local", "bin"),
+    ...process.platform === "win32" ? [] : ["/opt/homebrew/bin", "/usr/local/bin", "/usr/bin", "/bin"]
+  ];
+  const seen = /* @__PURE__ */ new Set();
+  const entries = [];
+  for (const candidate of candidates) {
+    const normalized = candidate.trim();
+    if (!normalized) {
+      continue;
+    }
+    const key = process.platform === "win32" ? normalized.toLowerCase() : normalized;
+    if (seen.has(key)) {
+      continue;
+    }
+    seen.add(key);
+    entries.push(normalized);
+  }
+  return entries.join(separator);
+}
+function plistEnvironmentEntries(environment) {
+  return Object.entries(environment).map(([key, value]) => `    <key>${xmlEscape(key)}</key>
+    <string>${xmlEscape(value)}</string>`).join("\n");
+}
+function systemdEnvironmentLines(environment) {
+  return Object.entries(environment).map(([key, value]) => `Environment=${systemdQuote(`${key}=${value}`)}`).join("\n");
+}
+function desktopEnvironmentArgs(environment) {
+  return Object.entries(environment).map(([key, value]) => desktopQuote(`${key}=${value}`)).join(" ");
+}
+function cmdEnvironmentLines(environment) {
+  return Object.entries(environment).map(
+    ([key, value]) => `set "${key}=${value.replaceAll('"', "")}"`
+  );
+}
 
 // src/i18n.ts
 var messages = {
@@ -303,6 +1544,25 @@ var messages = {
     "pair.autostartUnchanged": "Existing paired devices found. Boot autostart settings were left unchanged.",
     "pair.autostartFailed": "Pairing succeeded, but boot autostart could not be enabled: {message}",
     "doctor.description": "Run local diagnostics",
+    "doctor.installOnly": "only check npm global command and PATH setup",
+    "doctor.installHeader": "Install/PATH diagnostics:",
+    "doctor.installNpmPrefix": "npm global prefix: {value}",
+    "doctor.installGlobalBin": "npm global bin directory: {value}",
+    "doctor.installExpectedCommand": "expected hermeslink command: {value} ({state})",
+    "doctor.installCommandOnPath": "hermeslink found on PATH: {value}",
+    "doctor.installUnknown": "unknown",
+    "doctor.installOk": "ok",
+    "doctor.installMissing": "missing",
+    "doctor.installReady": "The global hermeslink command is visible to this shell.",
+    "doctor.installPrefixUnavailable": "Could not read npm global prefix with `{command} prefix -g`. Check that npm is available in this shell.",
+    "doctor.installExpectedMissing": "npm does not appear to have created the global hermeslink shim. Re-run `npm install -g @hermespilot/link` in the same system environment where Hermes runs.",
+    "doctor.installPathMissing": "npm installed hermeslink, but this shell cannot see npm's global bin directory on PATH.",
+    "doctor.installShadowed": "A different hermeslink command appears earlier on PATH. Remove the old command or move npm's global bin directory earlier on PATH.",
+    "doctor.installWslWindowsNpm": "This looks like Windows Node/npm being used from WSL (`/mnt/c/...`). Prefer installing Linux Node.js inside WSL, or run both Hermes Agent and Hermes Link on the Windows host.",
+    "doctor.installDirectRun": "Direct run without changing PATH: {command}",
+    "doctor.installUnixPathHint": 'Temporary PATH fix: export PATH="{path}:$PATH"',
+    "doctor.installWindowsPathHint": "Add this directory to your user Path, then open a new terminal: {path}",
+    "doctor.installNpxFallback": "PATH-independent fallback: npx --yes @hermespilot/link doctor --install",
     "doctor.identityOk": "Runtime identity: OK",
     "doctor.installId": "Install ID: {value}",
     "doctor.linkId": "Link ID: {value}",
@@ -401,6 +1661,25 @@ var messages = {
     "pair.autostartUnchanged": "\u68C0\u6D4B\u5230\u5DF2\u6709\u914D\u5BF9\u8BBE\u5907\uFF0C\u5F00\u673A\u81EA\u542F\u8BBE\u7F6E\u4FDD\u6301\u4E0D\u53D8\u3002",
     "pair.autostartFailed": "\u914D\u5BF9\u5DF2\u6210\u529F\uFF0C\u4F46\u542F\u7528\u5F00\u673A\u81EA\u542F\u5931\u8D25\uFF1A{message}",
     "doctor.description": "\u8FD0\u884C\u672C\u673A\u8BCA\u65AD",
+    "doctor.installOnly": "\u53EA\u68C0\u67E5 npm \u5168\u5C40\u547D\u4EE4\u548C PATH \u8BBE\u7F6E",
+    "doctor.installHeader": "\u5B89\u88C5 / PATH \u8BCA\u65AD\uFF1A",
+    "doctor.installNpmPrefix": "npm \u5168\u5C40 prefix\uFF1A{value}",
+    "doctor.installGlobalBin": "npm \u5168\u5C40 bin \u76EE\u5F55\uFF1A{value}",
+    "doctor.installExpectedCommand": "\u9884\u671F\u7684 hermeslink \u547D\u4EE4\uFF1A{value}\uFF08{state}\uFF09",
+    "doctor.installCommandOnPath": "\u5F53\u524D PATH \u627E\u5230\u7684 hermeslink\uFF1A{value}",
+    "doctor.installUnknown": "\u672A\u77E5",
+    "doctor.installOk": "\u5B58\u5728",
+    "doctor.installMissing": "\u672A\u627E\u5230",
+    "doctor.installReady": "\u5F53\u524D shell \u53EF\u4EE5\u76F4\u63A5\u627E\u5230\u5168\u5C40 hermeslink \u547D\u4EE4\u3002",
+    "doctor.installPrefixUnavailable": "\u65E0\u6CD5\u901A\u8FC7 `{command} prefix -g` \u8BFB\u53D6 npm \u5168\u5C40 prefix\u3002\u8BF7\u5148\u786E\u8BA4\u5F53\u524D shell \u80FD\u8FD0\u884C npm\u3002",
+    "doctor.installExpectedMissing": "npm \u4F3C\u4E4E\u6CA1\u6709\u521B\u5EFA\u5168\u5C40 hermeslink shim\u3002\u8BF7\u5728 Hermes \u6240\u5728\u7684\u540C\u4E00\u7CFB\u7EDF\u73AF\u5883\u91CC\u91CD\u65B0\u6267\u884C `npm install -g @hermespilot/link`\u3002",
+    "doctor.installPathMissing": "npm \u5DF2\u5B89\u88C5 hermeslink\uFF0C\u4F46\u5F53\u524D shell \u7684 PATH \u91CC\u6CA1\u6709 npm \u5168\u5C40 bin \u76EE\u5F55\u3002",
+    "doctor.installShadowed": "PATH \u524D\u9762\u5B58\u5728\u53E6\u4E00\u4E2A hermeslink \u547D\u4EE4\u3002\u8BF7\u5220\u9664\u65E7\u547D\u4EE4\uFF0C\u6216\u628A npm \u5168\u5C40 bin \u76EE\u5F55\u653E\u5230 PATH \u66F4\u524D\u9762\u3002",
+    "doctor.installWslWindowsNpm": "\u5F53\u524D\u770B\u8D77\u6765\u662F\u5728 WSL \u4E2D\u8C03\u7528\u4E86 Windows Node/npm\uFF08`/mnt/c/...`\uFF09\u3002\u5EFA\u8BAE\u5728 WSL \u5185\u5B89\u88C5 Linux \u7248 Node.js\uFF0C\u6216\u628A Hermes Agent \u4E0E Hermes Link \u90FD\u653E\u5728 Windows \u5BBF\u4E3B\u673A\u8FD0\u884C\u3002",
+    "doctor.installDirectRun": "\u4E0D\u6539 PATH \u4E5F\u53EF\u4EE5\u76F4\u63A5\u8FD0\u884C\uFF1A{command}",
+    "doctor.installUnixPathHint": '\u4E34\u65F6\u8865 PATH\uFF1Aexport PATH="{path}:$PATH"',
+    "doctor.installWindowsPathHint": "\u628A\u8FD9\u4E2A\u76EE\u5F55\u52A0\u5165\u5F53\u524D\u7528\u6237\u7684 Path\uFF0C\u7136\u540E\u91CD\u65B0\u6253\u5F00\u7EC8\u7AEF\uFF1A{path}",
+    "doctor.installNpxFallback": "\u4E0D\u4F9D\u8D56 PATH \u7684\u515C\u5E95\u547D\u4EE4\uFF1Anpx --yes @hermespilot/link doctor --install",
     "doctor.identityOk": "\u8FD0\u884C\u8EAB\u4EFD\uFF1A\u6B63\u5E38",
     "doctor.installId": "Install ID\uFF1A{value}",
     "doctor.linkId": "Link ID\uFF1A{value}",
@@ -515,12 +1794,12 @@ function parseLanguage(value) {
 
 // src/pairing/preflight.ts
 import { access, stat } from "fs/promises";
-import path2 from "path";
+import path3 from "path";
 async function assertPairingPreflightReady(options = {}) {
   const profileName = normalizeProfileName(options.profileName);
   const hermesHome = resolveHermesProfileDir(profileName);
   const configPath = resolveHermesConfigPath(profileName);
-  const envPath = path2.join(hermesHome, ".env");
+  const envPath = path3.join(hermesHome, ".env");
   const failures = [];
   options.onProgress?.("hermes_files");
   if (!await isDirectory(hermesHome)) {
@@ -664,7 +1943,7 @@ function normalizeProfileName(profileName) {
 }
 
 // src/runtime/browser.ts
-import { spawn } from "child_process";
+import { spawn as spawn2 } from "child_process";
 async function openSystemBrowser(url) {
   const platform = process.platform;
   if (platform === "win32") {
@@ -686,7 +1965,7 @@ async function spawnDetached(command, args) {
       resolve(ok);
     };
     try {
-      const child = spawn(command, args, {
+      const child = spawn2(command, args, {
         detached: true,
         stdio: "ignore"
       });
@@ -701,6 +1980,135 @@ async function spawnDetached(command, args) {
   });
 }
 
+// src/runtime/install-info.ts
+import { execFileSync } from "child_process";
+import { existsSync, realpathSync } from "fs";
+import path4 from "path";
+function readInstallPathInfo() {
+  return inspectInstallPath({
+    npmPrefix: resolveGlobalPrefix()
+  });
+}
+function inspectInstallPath(options = {}) {
+  const platform = options.platform ?? process.platform;
+  const env = options.env ?? process.env;
+  const exists = options.exists ?? existsSync;
+  const realpath = options.realpath ?? realpathSync;
+  const npmPrefix = options.npmPrefix === void 0 ? resolveGlobalPrefix(platform, env) : options.npmPrefix;
+  const globalBinDir = npmPrefix ? resolveGlobalBinDir(npmPrefix, platform) : null;
+  const expectedCommandPath = globalBinDir ? resolveGlobalCommandPath(globalBinDir, platform) : null;
+  const expectedCommandExists = expectedCommandPath ? exists(expectedCommandPath) : false;
+  const pathIncludesGlobalBin = globalBinDir ? pathIncludes(globalBinDir, env.PATH ?? "", platform) : false;
+  const commandOnPath = findCommandOnPath(LINK_COMMAND, env, platform, exists);
+  const commandOnPathMatchesExpected = commandOnPath && expectedCommandPath ? samePath(commandOnPath, expectedCommandPath, platform, realpath) : null;
+  return {
+    platform,
+    npmCommand: resolveNpmCommand(platform),
+    npmPrefix,
+    globalBinDir,
+    expectedCommandPath,
+    expectedCommandExists,
+    pathIncludesGlobalBin,
+    commandOnPath,
+    commandOnPathMatchesExpected,
+    wslWindowsNpmLikely: platform === "linux" && Boolean(npmPrefix?.startsWith("/mnt/c/"))
+  };
+}
+function hasInstallPathIssue(info) {
+  return !info.npmPrefix || !info.globalBinDir || !info.expectedCommandExists || !info.pathIncludesGlobalBin || !info.commandOnPath || info.commandOnPathMatchesExpected === false || info.wslWindowsNpmLikely;
+}
+function resolveGlobalBinDir(prefix, platform) {
+  return platform === "win32" ? prefix : pathForPlatform(platform).join(prefix, "bin");
+}
+function resolveGlobalCommandPath(binDir, platform) {
+  return pathForPlatform(platform).join(
+    binDir,
+    platform === "win32" ? `${LINK_COMMAND}.cmd` : LINK_COMMAND
+  );
+}
+function formatShellCommand(commandPath, args, platform) {
+  return [quoteShellToken(commandPath, platform), ...args.map((arg) => quoteShellToken(arg, platform))].join(" ");
+}
+function resolveGlobalPrefix(platform = process.platform, env = process.env) {
+  const envPrefix = env.npm_config_prefix?.trim() ?? env.npm_config_global_prefix?.trim() ?? "";
+  if (envPrefix) {
+    return envPrefix;
+  }
+  try {
+    const output = execFileSync(resolveNpmCommand(platform), ["prefix", "-g"], {
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "ignore"],
+      timeout: 2e3
+    });
+    return output.trim() || null;
+  } catch {
+    return null;
+  }
+}
+function resolveNpmCommand(platform) {
+  return platform === "win32" ? "npm.cmd" : "npm";
+}
+function pathIncludes(target, pathValue, platform) {
+  const normalizedTarget = normalizePath(target, platform);
+  return splitPath(pathValue, platform).some(
+    (entry) => normalizePath(entry, platform) === normalizedTarget
+  );
+}
+function findCommandOnPath(command, env, platform, exists) {
+  for (const entry of splitPath(env.PATH ?? "", platform)) {
+    for (const fileName of commandFileNames(command, env, platform)) {
+      const candidate = pathForPlatform(platform).join(entry, fileName);
+      if (exists(candidate)) {
+        return candidate;
+      }
+    }
+  }
+  return null;
+}
+function commandFileNames(command, env, platform) {
+  if (platform !== "win32") {
+    return [command];
+  }
+  const extensions = (env.PATHEXT || ".COM;.EXE;.BAT;.CMD;.PS1").split(";").map((value) => value.trim()).filter(Boolean);
+  return [command, ...extensions.map((extension) => `${command}${extension.toLowerCase()}`)];
+}
+function samePath(left, right, platform, realpath) {
+  try {
+    return normalizeComparablePath(realpath(left), platform) === normalizeComparablePath(realpath(right), platform);
+  } catch {
+    return normalizeComparablePath(left, platform) === normalizeComparablePath(right, platform);
+  }
+}
+function splitPath(pathValue, platform) {
+  const delimiter = platform === "win32" ? ";" : ":";
+  return pathValue.split(delimiter).map((entry) => stripPathQuotes(entry.trim())).filter(Boolean);
+}
+function stripPathQuotes(value) {
+  if (value.length >= 2 && value.startsWith('"') && value.endsWith('"')) {
+    return value.slice(1, -1);
+  }
+  return value;
+}
+function normalizePath(value, platform) {
+  return normalizeComparablePath(pathForPlatform(platform).resolve(value), platform);
+}
+function normalizeComparablePath(value, platform) {
+  const normalized = pathForPlatform(platform).normalize(value);
+  return platform === "win32" ? normalized.toLowerCase() : normalized;
+}
+function pathForPlatform(platform) {
+  return platform === "win32" ? path4.win32 : path4.posix;
+}
+function quoteShellToken(value, platform) {
+  if (/^[A-Za-z0-9_./:@%+=,-]+$/u.test(value)) {
+    return value;
+  }
+  if (platform === "win32") {
+    return `"${value.replaceAll('"', '\\"')}"`;
+  }
+  return `'${value.replaceAll("'", "'\\''")}'`;
+}
+
 // src/cli/index.ts
 var program = new Command();
 var helpLanguage = detectSystemLanguage();
@@ -874,6 +2282,7 @@ program.command("pair").description(helpText("pair.description")).action(async (
   const hadActiveDevices = await hasActiveDevices(paths);
   const probeBeforePair = await probeLocalLinkService({ port: config.port });
   const prepared = await preparePairing(paths);
+  const streamBatchPolicy = await fetchRelayStreamBatchPolicy(config.serverBaseUrl);
   await clearPairingClaim(prepared.sessionId, paths);
   const probe = await probeLocalLinkService({ port: config.port, linkId: prepared.linkId });
   if (probe.reachable && !probe.reusable) {
@@ -892,7 +2301,8 @@ program.command("pair").description(helpText("pair.description")).action(async (
     pairingRelayBridge = connectRelayControl({
       relayBaseUrl: prepared.relayBaseUrl,
       linkId: prepared.linkId,
-      localPort: config.port
+      localPort: config.port,
+      initialStreamBatchPolicy: streamBatchPolicy
     });
     pairingRelayBridge.publishNetworkRoutes(prepared.routes);
   }
@@ -999,7 +2409,17 @@ program.command("logs").description(helpText("logs.description")).action(async (
   console.log(t("logs.servicePath", { path: getLinkLogFile(paths) }));
   console.log(t("logs.daemonPath", { path: daemonLogFile(paths) }));
 });
-program.command("doctor").description(helpText("doctor.description")).action(async () => {
+program.command("doctor").option("--install", helpText("doctor.installOnly")).description(helpText("doctor.description")).action(async (options) => {
+  const installInfo = readInstallPathInfo();
+  const installLanguage = await loadCliLanguage().catch(() => detectSystemLanguage());
+  const installT = translate.bind(null, installLanguage);
+  if (options.install) {
+    printInstallDiagnostics(installInfo, installT, true);
+    return;
+  }
+  if (hasInstallPathIssue(installInfo)) {
+    printInstallDiagnostics(installInfo, installT, false);
+  }
   const [identity, config] = await Promise.all([ensureIdentity(), loadConfig()]);
   const language = resolveLanguage(config.language);
   const t = translate.bind(null, language);
@@ -1045,6 +2465,53 @@ async function loadCliLanguage() {
 function formatHermesVersion(version) {
   return version.version ?? version.raw;
 }
+function printInstallDiagnostics(info, t, verbose) {
+  if (!verbose && !hasInstallPathIssue(info)) {
+    return;
+  }
+  console.log(t("doctor.installHeader"));
+  console.log(t("doctor.installNpmPrefix", { value: info.npmPrefix ?? t("doctor.installUnknown") }));
+  console.log(t("doctor.installGlobalBin", { value: info.globalBinDir ?? t("doctor.installUnknown") }));
+  console.log(
+    t("doctor.installExpectedCommand", {
+      value: info.expectedCommandPath ?? t("doctor.installUnknown"),
+      state: info.expectedCommandExists ? t("doctor.installOk") : t("doctor.installMissing")
+    })
+  );
+  console.log(
+    t("doctor.installCommandOnPath", {
+      value: info.commandOnPath ?? t("doctor.installMissing")
+    })
+  );
+  if (!info.npmPrefix) {
+    console.log(t("doctor.installPrefixUnavailable", { command: info.npmCommand }));
+  } else if (!info.expectedCommandExists) {
+    console.log(t("doctor.installExpectedMissing"));
+  } else if (!info.pathIncludesGlobalBin || !info.commandOnPath) {
+    console.log(t("doctor.installPathMissing"));
+  } else if (info.commandOnPathMatchesExpected === false) {
+    console.log(t("doctor.installShadowed"));
+  } else {
+    console.log(t("doctor.installReady"));
+  }
+  if (info.wslWindowsNpmLikely) {
+    console.log(t("doctor.installWslWindowsNpm"));
+  }
+  if (info.expectedCommandPath && info.expectedCommandExists) {
+    console.log(
+      t("doctor.installDirectRun", {
+        command: formatShellCommand(info.expectedCommandPath, ["doctor"], info.platform)
+      })
+    );
+  }
+  if (info.globalBinDir && info.platform !== "win32") {
+    console.log(t("doctor.installUnixPathHint", { path: info.globalBinDir }));
+  }
+  if (info.globalBinDir && info.platform === "win32") {
+    console.log(t("doctor.installWindowsPathHint", { path: info.globalBinDir }));
+  }
+  console.log(t("doctor.installNpxFallback"));
+}
 function pairingPreflightProgressKey(stage) {
   switch (stage) {
     case "hermes_files":
@@ -1193,9 +2660,9 @@ function isCliEntrypoint(entry = process.argv[1], moduleUrl = import.meta.url) {
     return false;
   }
   try {
-    return moduleUrl === pathToFileURL(realpathSync(path3.resolve(entry))).href;
+    return moduleUrl === pathToFileURL(realpathSync2(path5.resolve(entry))).href;
   } catch {
-    return moduleUrl === pathToFileURL(path3.resolve(entry)).href;
+    return moduleUrl === pathToFileURL(path5.resolve(entry)).href;
   }
 }
 export {