herdr-remote 0.2.6 → 0.2.8

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2026 dibin
+Copyright (c) 2026 dibin666
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -45,6 +45,18 @@ herdr-remote plugin link
 - Settings: `~/.config/herdr-remote/config.json`
 - Runtime state: `~/.local/state/herdr-remote/runtime.json` (mode `0600`)
 
+## Locating Herdr
+
+The `herdr` binary is looked up in `HERDR_BIN_PATH`, then `PATH`, then the usual
+install directories (`~/.local/bin`, `~/.cargo/bin`, `~/bin`, `/opt/homebrew/bin`,
+`/usr/local/bin`, …). `herdr-remote keepalive install` writes the binary it found
+and the current `PATH` into the systemd unit or launchd agent, because a service
+manager does not inherit your shell's environment.
+
+`herdr-remote status --json` reports `host.herdrCommand` and `host.herdrCommandFound`.
+If it was not found, set `HERDR_BIN_PATH` to the full path and reinstall the
+keep-alive service.
+
 ## License
 
 MIT

package/README.zh-CN.md

@@ -45,6 +45,16 @@ herdr-remote plugin link
 - 配置文件：`~/.config/herdr-remote/config.json`
 - 运行状态：`~/.local/state/herdr-remote/runtime.json` (权限 `0600`)
 
+## herdr 命令的查找方式
+
+依次查找 `HERDR_BIN_PATH`、`PATH`，以及常见安装目录（`~/.local/bin`、`~/.cargo/bin`、
+`~/bin`、`/opt/homebrew/bin`、`/usr/local/bin` 等）。服务管理器不会继承 shell 环境，
+因此 `herdr-remote keepalive install` 会把找到的可执行文件路径和当前 `PATH` 写入
+systemd unit 或 launchd plist。
+
+`herdr-remote status --json` 会输出 `host.herdrCommand` 与 `host.herdrCommandFound`。
+若显示未找到，请将 `HERDR_BIN_PATH` 设为完整路径后重新安装保活服务。
+
 ## 开源协议
 
 MIT

package/dist/tui.mjs

@@ -526,7 +526,7 @@ var require_en = __commonJS({
       "herdr.registerDone": "Registered: {path}",
       "herdr.unregisterDone": "Plugin unregistered.",
       "herdr.registerFailed": "Registration failed: {message}",
-      "herdr.cliMissing": "Command herdr not found in PATH.",
+      "herdr.cliMissing": "Command herdr not found. Set HERDR_BIN_PATH to its full path.",
       "about.title": "Language & about",
       "about.language": "Interface language",
       "about.languageAuto": "Follow system ({detected})",
@@ -751,7 +751,7 @@ var require_zh = __commonJS({
       "herdr.registerDone": "\u5DF2\u6CE8\u518C\uFF1A{path}",
       "herdr.unregisterDone": "\u5DF2\u53D6\u6D88\u6CE8\u518C\u3002",
       "herdr.registerFailed": "\u6CE8\u518C\u5931\u8D25\uFF1A{message}",
-      "herdr.cliMissing": "PATH \u4E2D\u672A\u627E\u5230 herdr \u547D\u4EE4\u3002",
+      "herdr.cliMissing": "\u672A\u627E\u5230 herdr \u547D\u4EE4\uFF0C\u53EF\u5C06 HERDR_BIN_PATH \u8BBE\u4E3A\u5176\u5B8C\u6574\u8DEF\u5F84\u3002",
       "about.title": "\u8BED\u8A00\u4E0E\u5173\u4E8E",
       "about.language": "\u754C\u9762\u8BED\u8A00",
       "about.languageAuto": "\u8DDF\u968F\u7CFB\u7EDF\uFF08{detected}\uFF09",
@@ -1459,10 +1459,104 @@ var require_socket_discovery = __commonJS({
 var require_herdr_command = __commonJS({
   "src/herdr-command.js"(exports, module) {
     "use strict";
-    function resolveHerdrCommand() {
-      return process.env.HERDR_BIN_PATH || "herdr";
+    var fs = __require("node:fs");
+    var os = __require("node:os");
+    var path = __require("node:path");
+    var COMMAND_NAME = "herdr";
+    var FALLBACK_DIRECTORIES = [
+      "~/.local/bin",
+      "~/.cargo/bin",
+      "~/bin",
+      "/opt/homebrew/bin",
+      "/usr/local/bin",
+      "/home/linuxbrew/.linuxbrew/bin",
+      "/usr/bin"
+    ];
+    function expandHome(directory, home) {
+      if (directory === "~") return home;
+      if (directory.startsWith("~/")) return path.join(home, directory.slice(2));
+      return directory;
+    }
+    function candidateNames(base = COMMAND_NAME) {
+      return process.platform === "win32" ? [base, `${base}.exe`, `${base}.cmd`, `${base}.bat`] : [base];
+    }
+    function isExecutableFile(candidate) {
+      try {
+        if (!fs.statSync(candidate).isFile()) return false;
+        fs.accessSync(candidate, fs.constants.X_OK);
+        return true;
+      } catch {
+        return false;
+      }
+    }
+    function findInDirectory(directory, names = candidateNames()) {
+      if (!directory) return null;
+      for (const name of names) {
+        const candidate = path.join(directory, name);
+        if (isExecutableFile(candidate)) return candidate;
+      }
+      return null;
+    }
+    function findOnSearchPath(searchPath, names = candidateNames()) {
+      for (const entry of String(searchPath || "").split(path.delimiter)) {
+        const found = findInDirectory(entry.trim(), names);
+        if (found) return found;
+      }
+      return null;
     }
-    module.exports = { resolveHerdrCommand };
+    function fallbackDirectories(home = os.homedir()) {
+      return FALLBACK_DIRECTORIES.map((directory) => expandHome(directory, home));
+    }
+    function looksLikePath(value) {
+      return value.includes("/") || value.includes(path.sep);
+    }
+    function resolveOverride(value, searchPath) {
+      const trimmed = String(value || "").trim();
+      if (!trimmed) return null;
+      if (looksLikePath(trimmed)) {
+        const absolute = path.resolve(trimmed);
+        if (isExecutableFile(absolute)) return absolute;
+        return findInDirectory(absolute);
+      }
+      return findOnSearchPath(searchPath, candidateNames(trimmed));
+    }
+    function findHerdrCommand({ env = process.env, home = os.homedir(), directories = fallbackDirectories(home) } = {}) {
+      const override = resolveOverride(env.HERDR_BIN_PATH, env.PATH);
+      if (override) return { command: override, source: "env", found: true };
+      const onPath = findOnSearchPath(env.PATH);
+      if (onPath) return { command: onPath, source: "path", found: true };
+      for (const directory of directories) {
+        const found = findInDirectory(directory);
+        if (found) return { command: found, source: "fallback", found: true };
+      }
+      return { command: COMMAND_NAME, source: "unresolved", found: false };
+    }
+    function resolveHerdrCommand(options) {
+      return findHerdrCommand(options).command;
+    }
+    function verifyHerdrCommand(command, options = {}) {
+      if (typeof command === "string" && looksLikePath(command) && isExecutableFile(command)) {
+        return { command, source: "verified", found: true };
+      }
+      return findHerdrCommand(options);
+    }
+    function herdrNotFoundMessage({ env = process.env, home = os.homedir(), directories = fallbackDirectories(home) } = {}) {
+      const override = String(env.HERDR_BIN_PATH || "").trim();
+      const parts = [`Herdr executable "${COMMAND_NAME}" was not found.`];
+      if (override) parts.push(`HERDR_BIN_PATH=${override} does not point at an executable.`);
+      parts.push(directories.length ? `Searched PATH and ${directories.join(", ")}.` : "Searched PATH.");
+      parts.push("Install Herdr or set HERDR_BIN_PATH to its full path, then restart herdr-remote.");
+      return parts.join(" ");
+    }
+    module.exports = {
+      COMMAND_NAME,
+      FALLBACK_DIRECTORIES,
+      fallbackDirectories,
+      findHerdrCommand,
+      herdrNotFoundMessage,
+      resolveHerdrCommand,
+      verifyHerdrCommand
+    };
   }
 });
 
@@ -1496,7 +1590,7 @@ var require_service = __commonJS({
     } = require_terminal_palette();
     var { resolveSocketPath } = require_socket_discovery();
     var { preferredLanAddress: preferredLanAddress2 } = require_net_interfaces();
-    var { resolveHerdrCommand } = require_herdr_command();
+    var { findHerdrCommand, resolveHerdrCommand } = require_herdr_command();
     var RUNTIME_VERSION = 2;
     function pidAlive(pid) {
       if (!Number.isInteger(pid) || pid <= 0) return false;
@@ -1802,6 +1896,7 @@ var require_service = __commonJS({
         health = { ok: false, message: error.message };
       }
       const socketPath = resolveSocketPath(config.herdr.socketPath);
+      const herdr = findHerdrCommand();
       return {
         ok: true,
         mode: config.relay.mode,
@@ -1819,7 +1914,10 @@ var require_service = __commonJS({
           alive: pidAlive(state.hostPid),
           hostId: state.hostId || null,
           socketPath,
-          socketExists: Boolean(socketPath) && fs.existsSync(socketPath)
+          socketExists: Boolean(socketPath) && fs.existsSync(socketPath),
+          herdrCommand: herdr.command,
+          herdrCommandFound: herdr.found,
+          herdrCommandSource: herdr.source
         },
         publicUrl: resolvePublicUrl2(config, lanAddress),
         startedAt: state.startedAt || null
@@ -1896,6 +1994,7 @@ var require_keepalive = __commonJS({
     var { PACKAGE_ROOT, loadConfig: loadConfig2, stateDir: stateDir2 } = require_config();
     var { ensureDir, readJson, writeJsonAtomic } = require_state();
     var { logPath, pidAlive } = require_service();
+    var { findHerdrCommand } = require_herdr_command();
     var SYSTEMD_UNIT_NAME = "herdr-remote.service";
     var LAUNCHD_LABEL = "dev.herdr.remote";
     var FALLBACK_PID_FILE = "supervisor.pid";
@@ -1936,8 +2035,28 @@ var require_keepalive = __commonJS({
       }
       return "supervisor";
     }
+    function servicePath({ env = process.env, herdrCommand = null } = {}) {
+      const entries = String(env.PATH || "").split(path.delimiter).map((entry) => entry.trim()).filter(Boolean);
+      if (herdrCommand) entries.push(path.dirname(herdrCommand));
+      const seen = /* @__PURE__ */ new Set();
+      const unique = entries.filter((entry) => seen.has(entry) ? false : seen.add(entry));
+      return unique.join(path.delimiter);
+    }
+    function serviceEnvironment({ env = process.env, home = os.homedir(), directories } = {}) {
+      const environment = {};
+      const herdr = findHerdrCommand({ env, home, ...directories ? { directories } : {} });
+      if (herdr.found) environment.HERDR_BIN_PATH = herdr.command;
+      const searchPath = servicePath({ env, herdrCommand: herdr.found ? herdr.command : null });
+      if (searchPath) environment.PATH = searchPath;
+      return environment;
+    }
+    function systemdEnvironmentLine(key, value) {
+      const text = String(value).replace(/[\r\n]+/g, " ").replace(/%/g, "%%");
+      if (/^[\w@+=:,./-]*$/.test(text)) return `Environment=${key}=${text}`;
+      return `Environment="${key}=${text.replace(/([\\"])/g, "\\$1")}"`;
+    }
     function renderSystemdUnit({ nodePath = process.execPath, entryPoint = cliEntryPoint(), environment = {} } = {}) {
-      const environmentLines = Object.entries(environment).map(([key, value]) => `Environment=${key}=${value}`).join("\n");
+      const environmentLines = Object.entries(environment).map(([key, value]) => systemdEnvironmentLine(key, value)).join("\n");
       return `[Unit]
 Description=Herdr Remote (relay and host connector)
 Documentation=https://github.com/herdr/herdr-remote
@@ -2025,7 +2144,7 @@ ${environmentBlock}    <key>StandardOutPath</key>
     function systemdInstall() {
       const unitPath = systemdUnitPath();
       ensureDir(path.dirname(unitPath));
-      fs.writeFileSync(unitPath, renderSystemdUnit(), { mode: 420 });
+      fs.writeFileSync(unitPath, renderSystemdUnit({ environment: serviceEnvironment() }), { mode: 420 });
       const reload = systemctl(["daemon-reload"]);
       if (reload.status !== 0) {
         throw new Error(`systemctl --user daemon-reload failed: ${String(reload.stderr || "").trim()}`);
@@ -2065,7 +2184,7 @@ ${environmentBlock}    <key>StandardOutPath</key>
       const plistPath = launchdPlistPath();
       ensureDir(path.dirname(plistPath));
       ensureDir(stateDir2());
-      fs.writeFileSync(plistPath, renderLaunchdPlist(), { mode: 420 });
+      fs.writeFileSync(plistPath, renderLaunchdPlist({ environment: serviceEnvironment() }), { mode: 420 });
       spawnSync("launchctl", ["bootout", `${launchdDomainTarget()}/${LAUNCHD_LABEL}`], { stdio: "ignore" });
       const result = spawnSync("launchctl", ["bootstrap", launchdDomainTarget(), plistPath], { encoding: "utf8" });
       if (result.status !== 0) {
@@ -2104,7 +2223,7 @@ ${environmentBlock}    <key>StandardOutPath</key>
       try {
         const child = spawn(process.execPath, [cliEntryPoint(), "run", "--daemon"], {
           cwd: PACKAGE_ROOT,
-          env: { ...process.env, HERDR_REMOTE_SERVICE: "1" },
+          env: { ...process.env, HERDR_REMOTE_SERVICE: "1", ...serviceEnvironment() },
           detached: true,
           stdio: ["ignore", logFd, logFd]
         });
@@ -2209,6 +2328,9 @@ ${environmentBlock}    <key>StandardOutPath</key>
       renderSystemdUnit,
       renderLaunchdPlist,
       escapeXml,
+      servicePath,
+      serviceEnvironment,
+      systemdEnvironmentLine,
       status,
       install,
       uninstall,
@@ -2275,17 +2397,18 @@ var require_herdr_plugin = __commonJS({
     var path = __require("node:path");
     var { spawnSync } = __require("node:child_process");
     var { PACKAGE_ROOT } = require_config();
+    var { resolveHerdrCommand } = require_herdr_command();
     var PLUGIN_ID = "herdr.remote.web";
     var MANIFEST_NAME = "herdr-plugin.toml";
     function manifestPath() {
       return path.join(PACKAGE_ROOT, MANIFEST_NAME);
     }
     function herdrAvailable() {
-      const result = spawnSync("herdr", ["--version"], { stdio: "ignore" });
+      const result = spawnSync(resolveHerdrCommand(), ["--version"], { stdio: "ignore" });
       return result.status === 0 || result.status === 1;
     }
     function runHerdr(args, { timeout = 15e3 } = {}) {
-      const result = spawnSync("herdr", args, { encoding: "utf8", timeout });
+      const result = spawnSync(resolveHerdrCommand(), args, { encoding: "utf8", timeout });
       if (result.error && result.error.code === "ENOENT") {
         const error = new Error("herdr command not found");
         error.code = "HERDR_NOT_FOUND";
@@ -3889,7 +4012,7 @@ function About({ ctx }) {
         children: updateLabel
       }
     ) }),
-    /* @__PURE__ */ jsx10(Row, { label: t("about.version"), children: /* @__PURE__ */ jsx10(Text9, { color: theme.muted, children: "0.2.6" }) }),
+    /* @__PURE__ */ jsx10(Row, { label: t("about.version"), children: /* @__PURE__ */ jsx10(Text9, { color: theme.muted, children: "0.2.8" }) }),
     /* @__PURE__ */ jsx10(Row, { label: t("about.configPath"), children: /* @__PURE__ */ jsx10(Text9, { color: theme.muted, children: (0, import_config.configPath)() }) }),
     /* @__PURE__ */ jsx10(Row, { label: t("about.statePath"), children: /* @__PURE__ */ jsx10(Text9, { color: theme.muted, children: (0, import_config.stateDir)() }) }),
     /* @__PURE__ */ jsx10(Box9, { marginTop: 1, children: /* @__PURE__ */ jsx10(Text9, { color: theme.muted, children: t("about.docs") }) }),

package/herdr-plugin.toml

@@ -1,6 +1,6 @@
 id = "herdr.remote.web"
 name = "Herdr Remote Web"
-version = "0.2.6"
+version = "0.2.8"
 min_herdr_version = "0.9.0"
 description = "Browser access to Herdr workspaces via local or self-hosted relay"
 platforms = ["linux", "macos"]

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "herdr-remote",
-  "version": "0.2.6",
+  "version": "0.2.8",
   "description": "Browser access to Herdr workspaces: plugin, host connector, and configuration TUI",
   "license": "MIT",
   "repository": {

package/src/herdr-command.js

@@ -3,10 +3,157 @@
 // How a spawned Herdr is located.
 //
 // `HERDR_BIN_PATH` is what the service layer hands to the host connector, and
-// it is also the escape hatch for an install that is not on `PATH`.
+// it is also the escape hatch for an install that is not on `PATH`. Neither is
+// enough on its own once a service manager is in the picture: `systemd --user`
+// and `launchd` start their units with a minimal `PATH` that contains none of
+// the directories a user-level install writes to. A bare `herdr` then reaches
+// `execvp(3)` inside the forked PTY child, which prints
+// "execvp(3) failed.: No such file or directory" and exits — the failure the
+// browser sees as an endless reconnect loop.
+//
+// So the name is resolved to an absolute path here, ahead of any spawn:
+// an honoured override first, then `PATH`, then the handful of directories
+// installers actually use.
+
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+
+const COMMAND_NAME = 'herdr';
+
+/** Where a user-level install lands, in the order we trust it. */
+const FALLBACK_DIRECTORIES = [
+  '~/.local/bin',
+  '~/.cargo/bin',
+  '~/bin',
+  '/opt/homebrew/bin',
+  '/usr/local/bin',
+  '/home/linuxbrew/.linuxbrew/bin',
+  '/usr/bin',
+];
+
+function expandHome(directory, home) {
+  if (directory === '~') return home;
+  if (directory.startsWith('~/')) return path.join(home, directory.slice(2));
+  return directory;
+}
+
+/** Windows keeps the executable bit in the extension instead of the mode. */
+function candidateNames(base = COMMAND_NAME) {
+  return process.platform === 'win32'
+    ? [base, `${base}.exe`, `${base}.cmd`, `${base}.bat`]
+    : [base];
+}
+
+function isExecutableFile(candidate) {
+  try {
+    if (!fs.statSync(candidate).isFile()) return false;
+    fs.accessSync(candidate, fs.constants.X_OK);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function findInDirectory(directory, names = candidateNames()) {
+  if (!directory) return null;
+  for (const name of names) {
+    const candidate = path.join(directory, name);
+    if (isExecutableFile(candidate)) return candidate;
+  }
+  return null;
+}
+
+function findOnSearchPath(searchPath, names = candidateNames()) {
+  for (const entry of String(searchPath || '').split(path.delimiter)) {
+    const found = findInDirectory(entry.trim(), names);
+    if (found) return found;
+  }
+  return null;
+}
+
+function fallbackDirectories(home = os.homedir()) {
+  return FALLBACK_DIRECTORIES.map((directory) => expandHome(directory, home));
+}
+
+function looksLikePath(value) {
+  return value.includes('/') || value.includes(path.sep);
+}
+
+/**
+ * Honour `HERDR_BIN_PATH`.
+ *
+ * It is documented as the executable, but a directory is an easy thing to
+ * write there, and a bare name — someone copying `herdr` into a unit file —
+ * still has to go through the search. A value that resolves to nothing is
+ * treated as absent rather than fatal: a stale override left behind by a
+ * moved install is precisely the case we are trying to survive.
+ */
+function resolveOverride(value, searchPath) {
+  const trimmed = String(value || '').trim();
+  if (!trimmed) return null;
+  if (looksLikePath(trimmed)) {
+    const absolute = path.resolve(trimmed);
+    if (isExecutableFile(absolute)) return absolute;
+    return findInDirectory(absolute);
+  }
+  return findOnSearchPath(searchPath, candidateNames(trimmed));
+}
+
+/**
+ * Everything known about where Herdr is, so callers can report it and not only
+ * spawn it.
+ *
+ * `source` is `env` for an honoured `HERDR_BIN_PATH`, `path` for a hit on
+ * `PATH`, `fallback` for one of the well-known install directories, and
+ * `unresolved` when nothing matched. In that last case `command` is still the
+ * bare name: `PATH` may be right in a way we cannot see from here, and letting
+ * the spawn proceed keeps the old behaviour for anyone relying on it.
+ */
+function findHerdrCommand({ env = process.env, home = os.homedir(), directories = fallbackDirectories(home) } = {}) {
+  const override = resolveOverride(env.HERDR_BIN_PATH, env.PATH);
+  if (override) return { command: override, source: 'env', found: true };
+  const onPath = findOnSearchPath(env.PATH);
+  if (onPath) return { command: onPath, source: 'path', found: true };
+  for (const directory of directories) {
+    const found = findInDirectory(directory);
+    if (found) return { command: found, source: 'fallback', found: true };
+  }
+  return { command: COMMAND_NAME, source: 'unresolved', found: false };
+}
+
+function resolveHerdrCommand(options) {
+  return findHerdrCommand(options).command;
+}
+
+/**
+ * Re-check a command resolved earlier. A connector outlives the install that
+ * was missing when it started, and an absolute path outlives the binary it
+ * pointed at, so neither answer stays true for the life of the service.
+ */
+function verifyHerdrCommand(command, options = {}) {
+  if (typeof command === 'string' && looksLikePath(command) && isExecutableFile(command)) {
+    return { command, source: 'verified', found: true };
+  }
+  return findHerdrCommand(options);
+}
 
-function resolveHerdrCommand() {
-  return process.env.HERDR_BIN_PATH || 'herdr';
+/** The one message a user needs to fix a missing install themselves. */
+function herdrNotFoundMessage({ env = process.env, home = os.homedir(), directories = fallbackDirectories(home) } = {}) {
+  const override = String(env.HERDR_BIN_PATH || '').trim();
+  const parts = [`Herdr executable "${COMMAND_NAME}" was not found.`];
+  if (override) parts.push(`HERDR_BIN_PATH=${override} does not point at an executable.`);
+  parts.push(directories.length ? `Searched PATH and ${directories.join(', ')}.` : 'Searched PATH.');
+  parts.push('Install Herdr or set HERDR_BIN_PATH to its full path, then restart herdr-remote.');
+  return parts.join(' ');
 }
 
-module.exports = { resolveHerdrCommand };
+module.exports = {
+  COMMAND_NAME,
+  FALLBACK_DIRECTORIES,
+  fallbackDirectories,
+  findHerdrCommand,
+  herdrNotFoundMessage,
+  resolveHerdrCommand,
+  verifyHerdrCommand,
+};

package/src/herdr-plugin.js

@@ -10,6 +10,7 @@ const fs = require('node:fs');
 const path = require('node:path');
 const { spawnSync } = require('node:child_process');
 const { PACKAGE_ROOT } = require('./config');
+const { resolveHerdrCommand } = require('./herdr-command');
 
 const PLUGIN_ID = 'herdr.remote.web';
 const MANIFEST_NAME = 'herdr-plugin.toml';
@@ -18,13 +19,16 @@ function manifestPath() {
   return path.join(PACKAGE_ROOT, MANIFEST_NAME);
 }
 
+// Registration also runs from `herdr plugin` actions and from the service
+// manager, neither of which is guaranteed the PATH the user installed with, so
+// the command is resolved rather than named.
 function herdrAvailable() {
-  const result = spawnSync('herdr', ['--version'], { stdio: 'ignore' });
+  const result = spawnSync(resolveHerdrCommand(), ['--version'], { stdio: 'ignore' });
   return result.status === 0 || result.status === 1;
 }
 
 function runHerdr(args, { timeout = 15_000 } = {}) {
-  const result = spawnSync('herdr', args, { encoding: 'utf8', timeout });
+  const result = spawnSync(resolveHerdrCommand(), args, { encoding: 'utf8', timeout });
   if (result.error && result.error.code === 'ENOENT') {
     const error = new Error('herdr command not found');
     error.code = 'HERDR_NOT_FOUND';

package/src/host-connector.js

@@ -9,7 +9,7 @@ const { loadConfig, hostWebSocketUrl, resolveHostRelayUrl, stateDir } = require(
 const { ensureDir } = require('./state');
 const { resolveSocketPath, inspectSocket } = require('./socket-discovery');
 const { PtySession } = require('./pty-session');
-const { resolveHerdrCommand } = require('./herdr-command');
+const { resolveHerdrCommand, verifyHerdrCommand, herdrNotFoundMessage } = require('./herdr-command');
 // The wire format lives in the relay package so both ends of the protocol are
 // generated from one definition.
 const { packStreamFrame, unpackStreamFrame, PROTOCOL_VERSION } = require('herdr-remote-relay/protocol');
@@ -40,6 +40,14 @@ function pidAlive(pid) {
 }
 
 class HostConnector {
+  /**
+   * A session that dies this fast never really started. Anything longer is a
+   * session the user actually used and then left.
+   */
+  static FAST_FAILURE_MS = 1500;
+  /** How many broken starts in a row before we stop calling them exits. */
+  static FAST_FAILURE_LIMIT = 3;
+
   constructor(options = {}) {
     const config = options.config || loadConfig();
     this.config = config;
@@ -50,7 +58,10 @@ class HostConnector {
     // Optional; a relay without a password accepts any workstation.
     this.relayPassword = options.relayPassword ?? process.env.RELAY_PASSWORD ?? '';
     this.socketPath = options.socketPath || resolveSocketPath(config.herdr.socketPath);
-    this.herdrCommand = options.herdrCommand || resolveHerdrCommand();
+    // Where to look for Herdr when the command has to be resolved again; the
+    // real environment unless a caller narrows it.
+    this.herdrLookup = options.herdrLookup || {};
+    this.herdrCommand = options.herdrCommand || resolveHerdrCommand(this.herdrLookup);
     this.herdrArgs = options.herdrArgs || config.herdr.args;
     this.cwd = options.cwd || config.herdr.cwd;
     /**
@@ -65,6 +76,7 @@ class HostConnector {
       : resolveHostPalette();
     this.ws = null;
     this.sessions = new Map();
+    this.fastFailures = 0;
     this.reconnectTimer = null;
     this.heartbeatTimer = null;
     this.reconnectAttempts = 0;
@@ -270,10 +282,39 @@ class HostConnector {
     else if (message.type === 'resize') this.resizeSession(message);
   }
 
+  /**
+   * Confirm Herdr is really there before the name reaches `pty.spawn`.
+   *
+   * node-pty resolves the command with `execvp(3)` inside the forked child, so
+   * a missing binary is not a spawn error anyone can catch: the child writes
+   * "execvp(3) failed.: No such file or directory" into the PTY and exits. The
+   * `session_exit` that follows makes the relay drop the browser's socket, the
+   * browser reconnects into the same broken start, and that is the reconnect
+   * loop of issue #1. Refusing to start keeps the socket up and puts the actual
+   * reason in front of the user.
+   *
+   * Re-resolved per session rather than cached from the constructor: a service
+   * that started before Herdr was installed should pick it up without a restart.
+   */
+  ensureHerdrCommand() {
+    const resolved = verifyHerdrCommand(this.herdrCommand, this.herdrLookup);
+    if (resolved.found) {
+      this.herdrCommand = resolved.command;
+      return null;
+    }
+    return herdrNotFoundMessage(this.herdrLookup);
+  }
+
   startSession(message) {
     const streamId = typeof message.streamId === 'string' ? message.streamId : message.clientId;
     if (!streamId) return;
     this.stopSession(streamId);
+    const missingHerdr = this.ensureHerdrCommand();
+    if (missingHerdr) {
+      process.stderr.write(`herdr-remote host connector: ${missingHerdr}\n`);
+      sendJson(this.ws, { type: 'error', clientId: streamId, code: 'herdr_not_found', message: missingHerdr });
+      return;
+    }
     const socketInfo = inspectSocket(this.socketPath);
     if (!socketInfo.ok) {
       sendJson(this.ws, { type: 'error', clientId: streamId, code: 'herdr_socket_unavailable', message: socketInfo.reason });
@@ -291,6 +332,7 @@ class HostConnector {
       cols: Number(message.cols) || PtySession.DEFAULT_COLS,
       rows: Number(message.rows) || PtySession.DEFAULT_ROWS,
       createdAt: new Date().toISOString(),
+      startedAtMs: Date.now(),
       clientId: streamId,
     };
     try {
@@ -304,7 +346,7 @@ class HostConnector {
         onExit: ({ exitCode }) => {
           if (this.sessions.get(streamId) !== session) return;
           this.sessions.delete(streamId);
-          sendJson(this.ws, { type: 'session_exit', clientId: streamId, code: exitCode });
+          this.reportSessionExit(session, exitCode);
           this.sendHeartbeat();
         },
       });
@@ -318,6 +360,32 @@ class HostConnector {
     this.sendHeartbeat();
   }
 
+  /**
+   * Tell the relay how a session ended.
+   *
+   * `session_exit` is the honest answer for a session that ran, and the relay
+   * closes the browser's socket on it so the window can start a fresh one. That
+   * is also what turns a start that keeps failing into a reconnect loop: exit,
+   * close, reconnect, exit. Once a few starts in a row have died immediately
+   * with a non-zero code the failure is systemic, not a session ending, so it is
+   * reported as an error — which the relay forwards without dropping the socket,
+   * leaving the user with a message instead of a spinner.
+   */
+  reportSessionExit(session, exitCode) {
+    const streamId = session.id;
+    const lifetimeMs = Date.now() - session.startedAtMs;
+    const failedFast = exitCode !== 0 && lifetimeMs < HostConnector.FAST_FAILURE_MS;
+    this.fastFailures = failedFast ? this.fastFailures + 1 : 0;
+    if (this.fastFailures < HostConnector.FAST_FAILURE_LIMIT) {
+      sendJson(this.ws, { type: 'session_exit', clientId: streamId, code: exitCode });
+      return;
+    }
+    const message = `"${this.herdrCommand}" exited immediately with code ${exitCode} on ${this.fastFailures} attempts in a row. `
+      + 'Check that it runs from a terminal, and see the host connector log for what it printed.';
+    process.stderr.write(`herdr-remote host connector: ${message}\n`);
+    sendJson(this.ws, { type: 'error', clientId: streamId, code: 'herdr_start_failed', message });
+  }
+
   stopSession(streamId) {
     const session = this.sessions.get(streamId);
     if (!session) return;

package/src/i18n/en.js

@@ -154,7 +154,7 @@ module.exports = {
   'herdr.registerDone': 'Registered: {path}',
   'herdr.unregisterDone': 'Plugin unregistered.',
   'herdr.registerFailed': 'Registration failed: {message}',
-  'herdr.cliMissing': 'Command herdr not found in PATH.',
+  'herdr.cliMissing': 'Command herdr not found. Set HERDR_BIN_PATH to its full path.',
 
   'about.title': 'Language & about',
   'about.language': 'Interface language',

package/src/i18n/zh.js

@@ -153,7 +153,7 @@ module.exports = {
   'herdr.registerDone': '已注册：{path}',
   'herdr.unregisterDone': '已取消注册。',
   'herdr.registerFailed': '注册失败：{message}',
-  'herdr.cliMissing': 'PATH 中未找到 herdr 命令。',
+  'herdr.cliMissing': '未找到 herdr 命令，可将 HERDR_BIN_PATH 设为其完整路径。',
 
   'about.title': '语言与关于',
   'about.language': '界面语言',

package/src/keepalive.js

@@ -15,6 +15,7 @@ const { spawn, spawnSync } = require('node:child_process');
 const { PACKAGE_ROOT, loadConfig, stateDir } = require('./config');
 const { ensureDir, readJson, writeJsonAtomic } = require('./state');
 const { logPath, pidAlive } = require('./service');
+const { findHerdrCommand } = require('./herdr-command');
 
 const SYSTEMD_UNIT_NAME = 'herdr-remote.service';
 const LAUNCHD_LABEL = 'dev.herdr.remote';
@@ -71,13 +72,65 @@ function detectManager(preference = 'auto') {
   return 'supervisor';
 }
 
+// ---------------------------------------------------------------------------
+// The environment a supervised copy needs
+// ---------------------------------------------------------------------------
+
+/**
+ * `PATH` for the unit: the one that is resolving commands right now, plus the
+ * directory Herdr was found in.
+ *
+ * A service manager does not inherit the shell's environment. `systemd --user`
+ * hands a unit something close to `/usr/local/bin:/usr/bin:/bin` and `launchd`
+ * is no more generous, so a copy that works from a terminal loses `~/.local/bin`
+ * — and with it `herdr` — the moment it is installed as a service. Freezing the
+ * installing shell's `PATH` into the unit keeps the supervised copy able to find
+ * Herdr, and Herdr able to find the tools it spawns in turn.
+ */
+function servicePath({ env = process.env, herdrCommand = null } = {}) {
+  const entries = String(env.PATH || '')
+    .split(path.delimiter)
+    .map((entry) => entry.trim())
+    .filter(Boolean);
+  // The override already pins the exact binary; this is only so the session
+  // itself can still reach it by name.
+  if (herdrCommand) entries.push(path.dirname(herdrCommand));
+  const seen = new Set();
+  const unique = entries.filter((entry) => (seen.has(entry) ? false : seen.add(entry)));
+  return unique.join(path.delimiter);
+}
+
+/**
+ * What has to be written into the unit file for a supervised start to behave
+ * like the one the user just ran by hand.
+ */
+function serviceEnvironment({ env = process.env, home = os.homedir(), directories } = {}) {
+  const environment = {};
+  const herdr = findHerdrCommand({ env, home, ...(directories ? { directories } : {}) });
+  if (herdr.found) environment.HERDR_BIN_PATH = herdr.command;
+  const searchPath = servicePath({ env, herdrCommand: herdr.found ? herdr.command : null });
+  if (searchPath) environment.PATH = searchPath;
+  return environment;
+}
+
 // ---------------------------------------------------------------------------
 // Unit file rendering (pure, so it can be asserted in tests)
 // ---------------------------------------------------------------------------
 
+/**
+ * One `KEY=value` per directive. An unquoted systemd value ends at the first
+ * space, and `%` starts a specifier, so a `PATH` with either in it would be
+ * silently truncated or rewritten.
+ */
+function systemdEnvironmentLine(key, value) {
+  const text = String(value).replace(/[\r\n]+/g, ' ').replace(/%/g, '%%');
+  if (/^[\w@+=:,./-]*$/.test(text)) return `Environment=${key}=${text}`;
+  return `Environment="${key}=${text.replace(/([\\"])/g, '\\$1')}"`;
+}
+
 function renderSystemdUnit({ nodePath = process.execPath, entryPoint = cliEntryPoint(), environment = {} } = {}) {
   const environmentLines = Object.entries(environment)
-    .map(([key, value]) => `Environment=${key}=${value}`)
+    .map(([key, value]) => systemdEnvironmentLine(key, value))
     .join('\n');
   return `[Unit]
 Description=Herdr Remote (relay and host connector)
@@ -179,7 +232,7 @@ function systemdStatus() {
 function systemdInstall() {
   const unitPath = systemdUnitPath();
   ensureDir(path.dirname(unitPath));
-  fs.writeFileSync(unitPath, renderSystemdUnit(), { mode: 0o644 });
+  fs.writeFileSync(unitPath, renderSystemdUnit({ environment: serviceEnvironment() }), { mode: 0o644 });
   const reload = systemctl(['daemon-reload']);
   if (reload.status !== 0) {
     throw new Error(`systemctl --user daemon-reload failed: ${String(reload.stderr || '').trim()}`);
@@ -227,7 +280,7 @@ function launchdInstall() {
   const plistPath = launchdPlistPath();
   ensureDir(path.dirname(plistPath));
   ensureDir(stateDir());
-  fs.writeFileSync(plistPath, renderLaunchdPlist(), { mode: 0o644 });
+  fs.writeFileSync(plistPath, renderLaunchdPlist({ environment: serviceEnvironment() }), { mode: 0o644 });
   // bootout first so a re-install picks up the rewritten plist.
   spawnSync('launchctl', ['bootout', `${launchdDomainTarget()}/${LAUNCHD_LABEL}`], { stdio: 'ignore' });
   const result = spawnSync('launchctl', ['bootstrap', launchdDomainTarget(), plistPath], { encoding: 'utf8' });
@@ -275,7 +328,7 @@ function fallbackInstall() {
   try {
     const child = spawn(process.execPath, [cliEntryPoint(), 'run', '--daemon'], {
       cwd: PACKAGE_ROOT,
-      env: { ...process.env, HERDR_REMOTE_SERVICE: '1' },
+      env: { ...process.env, HERDR_REMOTE_SERVICE: '1', ...serviceEnvironment() },
       detached: true,
       stdio: ['ignore', logFd, logFd],
     });
@@ -394,6 +447,9 @@ module.exports = {
   renderSystemdUnit,
   renderLaunchdPlist,
   escapeXml,
+  servicePath,
+  serviceEnvironment,
+  systemdEnvironmentLine,
   status,
   install,
   uninstall,

package/src/service.js

@@ -26,7 +26,7 @@ const {
 } = require('./terminal-palette');
 const { resolveSocketPath } = require('./socket-discovery');
 const { preferredLanAddress } = require('./net-interfaces');
-const { resolveHerdrCommand } = require('./herdr-command');
+const { findHerdrCommand, resolveHerdrCommand } = require('./herdr-command');
 
 const RUNTIME_VERSION = 2;
 
@@ -415,6 +415,9 @@ async function statusServices() {
     health = { ok: false, message: error.message };
   }
   const socketPath = resolveSocketPath(config.herdr.socketPath);
+  // Where Herdr was found, and whether it was found at all: under a service
+  // manager this is the first thing to check when sessions will not start.
+  const herdr = findHerdrCommand();
   return {
     ok: true,
     mode: config.relay.mode,
@@ -433,6 +436,9 @@ async function statusServices() {
       hostId: state.hostId || null,
       socketPath,
       socketExists: Boolean(socketPath) && fs.existsSync(socketPath),
+      herdrCommand: herdr.command,
+      herdrCommandFound: herdr.found,
+      herdrCommandSource: herdr.source,
     },
     publicUrl: resolvePublicUrl(config, lanAddress),
     startedAt: state.startedAt || null,