herdr-remote 0.2.3 → 0.2.5

package/herdr-plugin.toml

@@ -2,7 +2,7 @@ id = "herdr.remote.web"
 name = "Herdr Remote Web"
 version = "0.2.3"
 min_herdr_version = "0.8.2"
-description = "Mobile-first remote access to the native Herdr TUI through a local or self-hosted relay"
+description = "Browser access to Herdr workspaces via local or self-hosted relay"
 platforms = ["linux", "macos"]
 
 # No [[build]] steps: this package is installed from npm with its TUI bundle and
@@ -20,31 +20,31 @@ command = ["node", "bin/herdr-remote.js"]
 
 [[actions]]
 id = "configure"
-title = "Configure Herdr Remote"
+title = "Configure"
 contexts = ["workspace", "pane"]
 command = ["herdr", "plugin", "pane", "open", "--plugin", "herdr.remote.web", "--entrypoint", "config", "--placement", "zoomed", "--focus"]
 
 [[actions]]
 id = "start"
-title = "Start Herdr Remote"
+title = "Start"
 contexts = ["workspace", "pane"]
 command = ["node", "bin/herdr-remote.js", "start"]
 
 [[actions]]
 id = "stop"
-title = "Stop Herdr Remote"
+title = "Stop"
 contexts = ["workspace", "pane"]
 command = ["node", "bin/herdr-remote.js", "stop"]
 
 [[actions]]
 id = "status"
-title = "Show Herdr Remote status"
+title = "Status"
 contexts = ["workspace", "pane"]
 command = ["node", "bin/herdr-remote.js", "status"]
 
 [[actions]]
 id = "pair"
-title = "Create a phone pairing code"
+title = "Pair"
 contexts = ["workspace", "pane"]
 command = ["node", "bin/herdr-remote.js", "pair"]
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "herdr-remote",
-  "version": "0.2.3",
-  "description": "Remote browser access to your Herdr terminal workspaces: Herdr plugin, host connector, and bilingual configuration TUI",
+  "version": "0.2.5",
+  "description": "Browser access to Herdr workspaces: plugin, host connector, and configuration TUI",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -32,7 +32,8 @@
     "dist",
     "src",
     "herdr-plugin.toml",
-    "config.example.json"
+    "config.example.json",
+    "README.zh-CN.md"
   ],
   "scripts": {
     "build": "node scripts/build-tui.mjs",

package/src/config.js

@@ -64,6 +64,10 @@ const DEFAULTS = {
     remoteUrl: '',
     maxPayloadBytes: 1024 * 1024,
     maxClientsPerHost: 16,
+    maxHosts: 1024,
+    maxPendingHandshakes: 1024,
+    maxBufferedBytesPerClient: 4 * 1024 * 1024,
+    hostReconnectGraceMs: 30 * 1000,
     allowedOrigins: [],
   },
   herdr: {
@@ -230,6 +234,20 @@ function validate(config) {
   config.relay.port = parseInteger(config.relay.port, DEFAULTS.relay.port, 1, 65535);
   config.relay.maxPayloadBytes = parseInteger(config.relay.maxPayloadBytes, DEFAULTS.relay.maxPayloadBytes, 4096, 16 * 1024 * 1024);
   config.relay.maxClientsPerHost = parseInteger(config.relay.maxClientsPerHost, DEFAULTS.relay.maxClientsPerHost, 1, 256);
+  config.relay.maxHosts = parseInteger(config.relay.maxHosts, DEFAULTS.relay.maxHosts, 1, 100000);
+  config.relay.maxPendingHandshakes = parseInteger(config.relay.maxPendingHandshakes, DEFAULTS.relay.maxPendingHandshakes, 16, 100000);
+  config.relay.maxBufferedBytesPerClient = parseInteger(
+    config.relay.maxBufferedBytesPerClient,
+    DEFAULTS.relay.maxBufferedBytesPerClient,
+    64 * 1024,
+    256 * 1024 * 1024,
+  );
+  config.relay.hostReconnectGraceMs = parseInteger(
+    config.relay.hostReconnectGraceMs,
+    DEFAULTS.relay.hostReconnectGraceMs,
+    1000,
+    24 * 60 * 60 * 1000,
+  );
   config.auth.pairingTtlMs = parseInteger(config.auth.pairingTtlMs, DEFAULTS.auth.pairingTtlMs, 30 * 1000, 24 * 60 * 60 * 1000);
   config.auth.deviceTtlMs = parseInteger(config.auth.deviceTtlMs, DEFAULTS.auth.deviceTtlMs, 60 * 1000, 365 * 24 * 60 * 60 * 1000);
   config.auth.maxDevices = parseInteger(config.auth.maxDevices, DEFAULTS.auth.maxDevices, 1, 10000);
@@ -277,6 +295,10 @@ function applyEnvironment(config) {
   if (env.RELAY_PORT) config.relay.port = env.RELAY_PORT;
   if (env.RELAY_PUBLIC_URL) config.relay.publicUrl = env.RELAY_PUBLIC_URL;
   if (env.RELAY_REMOTE_URL) config.relay.remoteUrl = env.RELAY_REMOTE_URL;
+  if (env.RELAY_MAX_HOSTS) config.relay.maxHosts = env.RELAY_MAX_HOSTS;
+  if (env.RELAY_MAX_PENDING_HANDSHAKES) config.relay.maxPendingHandshakes = env.RELAY_MAX_PENDING_HANDSHAKES;
+  if (env.RELAY_MAX_BUFFERED_BYTES_PER_CLIENT) config.relay.maxBufferedBytesPerClient = env.RELAY_MAX_BUFFERED_BYTES_PER_CLIENT;
+  if (env.RELAY_HOST_RECONNECT_GRACE_MS) config.relay.hostReconnectGraceMs = env.RELAY_HOST_RECONNECT_GRACE_MS;
   if (env.HERDR_SOCKET_PATH) config.herdr.socketPath = env.HERDR_SOCKET_PATH;
   if (env.HERDR_CWD) config.herdr.cwd = env.HERDR_CWD;
   if (env.HERDR_ARGS_JSON) {

package/src/exit-codes.js

@@ -10,5 +10,7 @@
  * one exit the supervisor must respect rather than recover from.
  */
 const EXIT_REPLACED = 12;
+/** Credentials need operator intervention; a supervisor must not loop. */
+const EXIT_AUTH_FAILED = 13;
 
-module.exports = { EXIT_REPLACED };
+module.exports = { EXIT_REPLACED, EXIT_AUTH_FAILED };

package/src/host-connector.js

@@ -1,9 +1,12 @@
 'use strict';
 
+const fs = require('node:fs');
 const os = require('node:os');
+const path = require('node:path');
 const crypto = require('node:crypto');
 const { WebSocket } = require('ws');
-const { loadConfig, hostWebSocketUrl, resolveHostRelayUrl } = require('./config');
+const { loadConfig, hostWebSocketUrl, resolveHostRelayUrl, stateDir } = require('./config');
+const { ensureDir } = require('./state');
 const { resolveSocketPath, inspectSocket } = require('./socket-discovery');
 const { PtySession } = require('./pty-session');
 const { resolveHerdrCommand } = require('./herdr-command');
@@ -11,7 +14,7 @@ const { resolveHerdrCommand } = require('./herdr-command');
 // generated from one definition.
 const { packStreamFrame, unpackStreamFrame, PROTOCOL_VERSION } = require('herdr-remote-relay/protocol');
 const { resolveHostPalette } = require('./terminal-palette');
-const { EXIT_REPLACED } = require('./exit-codes');
+const { EXIT_REPLACED, EXIT_AUTH_FAILED } = require('./exit-codes');
 
 function randomId(prefix) {
   return `${prefix}-${crypto.randomBytes(9).toString('base64url')}`;
@@ -21,9 +24,19 @@ function sendJson(ws, payload) {
   if (ws && ws.readyState === WebSocket.OPEN) ws.send(JSON.stringify(payload));
 }
 
-function closeSocket(ws) {
+function closeSocket(ws, reason = 'host connector stopping') {
   if (!ws || ws.readyState === WebSocket.CLOSED || ws.readyState === WebSocket.CLOSING) return;
-  try { ws.close(1000, 'host connector stopping'); } catch {}
+  try { ws.close(1000, reason); } catch {}
+}
+
+function pidAlive(pid) {
+  if (!Number.isInteger(pid) || pid <= 0) return false;
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (error) {
+    return error.code === 'EPERM';
+  }
 }
 
 class HostConnector {
@@ -55,13 +68,62 @@ class HostConnector {
     this.reconnectTimer = null;
     this.heartbeatTimer = null;
     this.reconnectAttempts = 0;
+    this.clientCount = 0;
+    this.legacyHeartbeat = false;
+    this.ready = false;
+    this.authFailure = false;
     this.stopping = false;
+    this.lockPath = options.lockPath
+      || process.env.HERDR_REMOTE_HOST_LOCK
+      || path.join(stateDir(), 'host-connector.lock');
+    this.lockFd = null;
+  }
+
+  acquireLock() {
+    if (this.lockFd !== null) return;
+    ensureDir(path.dirname(this.lockPath));
+    for (let attempt = 0; attempt < 2; attempt += 1) {
+      try {
+        const fd = fs.openSync(this.lockPath, 'wx', 0o600);
+        fs.writeFileSync(fd, `${JSON.stringify({ pid: process.pid, hostId: this.hostId, startedAt: new Date().toISOString() })}\n`);
+        this.lockFd = fd;
+        return;
+      } catch (error) {
+        if (error.code !== 'EEXIST') throw error;
+        let owner = null;
+        try { owner = JSON.parse(fs.readFileSync(this.lockPath, 'utf8')); } catch {}
+        if (owner && pidAlive(owner.pid)) {
+          const duplicate = new Error(`another host connector is already running (pid ${owner.pid})`);
+          duplicate.code = 'HOST_ALREADY_RUNNING';
+          throw duplicate;
+        }
+        try { fs.rmSync(this.lockPath, { force: true }); } catch {}
+      }
+    }
+    const stale = new Error('could not acquire host connector lock');
+    stale.code = 'HOST_LOCK_FAILED';
+    throw stale;
+  }
+
+  releaseLock() {
+    const owned = this.lockFd !== null;
+    if (this.lockFd !== null) {
+      try { fs.closeSync(this.lockFd); } catch {}
+      this.lockFd = null;
+    }
+    if (!owned) return;
+    try {
+      const owner = JSON.parse(fs.readFileSync(this.lockPath, 'utf8'));
+      if (owner.pid !== process.pid) return;
+    } catch {}
+    try { fs.rmSync(this.lockPath, { force: true }); } catch {}
   }
 
   start() {
     if (!this.hostToken) {
       throw new Error('RELAY_HOST_TOKEN is required');
     }
+    this.acquireLock();
     this.stopping = false;
     this.connect();
   }
@@ -72,9 +134,14 @@ class HostConnector {
     if (this.heartbeatTimer) clearInterval(this.heartbeatTimer);
     this.reconnectTimer = null;
     this.heartbeatTimer = null;
+    sendJson(this.ws, { type: 'host_shutdown' });
     this.destroySessions();
-    closeSocket(this.ws);
+    closeSocket(this.ws, 'host_shutdown');
     this.ws = null;
+    this.ready = false;
+    this.clientCount = 0;
+    this.legacyHeartbeat = false;
+    this.releaseLock();
   }
 
   connect() {
@@ -89,8 +156,9 @@ class HostConnector {
     this.ws = ws;
     ws.isAlive = true;
     ws.on('open', () => {
-      this.reconnectAttempts = 0;
       ws.isAlive = true;
+      this.ready = false;
+      this.authFailure = false;
       sendJson(ws, {
         type: 'host_hello',
         protocol: PROTOCOL_VERSION,
@@ -101,16 +169,24 @@ class HostConnector {
         platform: process.platform,
         arch: process.arch,
         terminalPalette: this.terminalPalette || null,
+        capabilities: ['host_handoff', 'idle_heartbeat'],
       });
-      this.sendHeartbeat();
-      this.heartbeatTimer = setInterval(() => this.sendHeartbeat(), this.config.cleanup.heartbeatIntervalMs);
+      // The relay sends host_ready with the current browser count. No business
+      // heartbeat is started until that message says somebody is watching.
     });
     ws.on('pong', () => { ws.isAlive = true; });
     ws.on('message', (raw, isBinary) => this.handleMessage(raw, isBinary));
     ws.on('close', (code, rawReason) => {
-      if (this.ws === ws) this.ws = null;
+      // A replacement socket may be live while an older socket is still
+      // delivering its close event. Never let that stale event destroy the new
+      // session or clear its heartbeat timer.
+      if (this.ws !== ws) return;
+      this.ws = null;
       if (this.heartbeatTimer) clearInterval(this.heartbeatTimer);
       this.heartbeatTimer = null;
+      this.ready = false;
+      this.clientCount = 0;
+      this.legacyHeartbeat = false;
       this.destroySessions();
 
       // Another connector has claimed this workstation. Reconnecting would just
@@ -123,6 +199,12 @@ class HostConnector {
         this.stop();
         process.exit(EXIT_REPLACED);
       }
+      if (this.authFailure) {
+        this.stopping = true;
+        process.stderr.write('herdr-remote host connector: authentication failed; update relay credentials and restart the service\n');
+        this.releaseLock();
+        process.exit(EXIT_AUTH_FAILED);
+      }
       this.scheduleReconnect();
     });
     ws.on('error', (error) => {
@@ -160,9 +242,29 @@ class HostConnector {
     // connection just closed silently and reconnected forever, leaving the user
     // with an empty log and no idea what was wrong.
     if (message.type === 'error' && !message.clientId) {
+      this.authFailure = ['relay_password_required', 'host_auth_failed', 'invalid_host_credentials'].includes(message.code);
       process.stderr.write(`herdr-remote host connector: relay rejected the connection: ${message.message || message.code}\n`);
       return;
     }
+    if (message.type === 'host_ready') {
+      this.ready = true;
+      this.reconnectAttempts = 0;
+      if (Object.hasOwn(message, 'clientCount')) {
+        this.legacyHeartbeat = false;
+        this.setClientCount(message.clientCount);
+      } else {
+        // An older relay does not know client_count. Keep its historical
+        // telemetry behavior so rolling upgrades do not silently lose status.
+        this.legacyHeartbeat = true;
+        this.sendHeartbeat(true);
+        this.heartbeatTimer = setInterval(() => this.sendHeartbeat(), this.config.cleanup.heartbeatIntervalMs);
+      }
+      return;
+    }
+    if (message.type === 'client_count') {
+      this.setClientCount(message.clientCount);
+      return;
+    }
     if (message.type === 'session_start') this.startSession(message);
     else if (message.type === 'session_stop') this.stopSession(message.clientId || message.streamId);
     else if (message.type === 'resize') this.resizeSession(message);
@@ -224,6 +326,22 @@ class HostConnector {
     this.sendHeartbeat();
   }
 
+  setClientCount(value) {
+    const next = Number.isInteger(value) ? Math.max(0, value) : 0;
+    if (next === this.clientCount && (next === 0 || this.heartbeatTimer)) return;
+    const wasActive = this.clientCount > 0;
+    this.clientCount = next;
+    if (next > 0) {
+      if (this.heartbeatTimer) clearInterval(this.heartbeatTimer);
+      this.sendHeartbeat(true);
+      this.heartbeatTimer = setInterval(() => this.sendHeartbeat(), this.config.cleanup.heartbeatIntervalMs);
+    } else {
+      if (this.heartbeatTimer) clearInterval(this.heartbeatTimer);
+      this.heartbeatTimer = null;
+      if (wasActive) this.sendHeartbeat(true);
+    }
+  }
+
   resizeSession(message) {
     const id = message.clientId || message.streamId;
     const session = this.sessions.get(id);
@@ -238,7 +356,8 @@ class HostConnector {
     this.sessions.clear();
   }
 
-  sendHeartbeat() {
+  sendHeartbeat(force = false) {
+    if (!force && this.clientCount <= 0 && !this.legacyHeartbeat) return;
     const memory = process.memoryUsage();
     const load = os.loadavg();
     sendJson(this.ws, {
@@ -270,7 +389,7 @@ if (require.main === module) {
     connector.start();
   } catch (error) {
     process.stderr.write(`herdr-remote host connector failed: ${error.message}\n`);
-    process.exitCode = 1;
+    process.exitCode = error.code === 'HOST_ALREADY_RUNNING' ? EXIT_REPLACED : 1;
   }
   const stop = () => { connector.stop(); process.exit(0); };
   process.once('SIGINT', stop);

package/src/i18n/en.js

@@ -5,7 +5,7 @@
 
 module.exports = {
   'app.name': 'Herdr Remote',
-  'app.tagline': 'Remote browser access to your Herdr workspaces',
+  'app.tagline': 'Remote browser access to Herdr workspaces',
 
   'common.yes': 'Yes',
   'common.no': 'No',
@@ -41,12 +41,12 @@ module.exports = {
 
   'mode.local': 'This machine only',
   'mode.lan': 'Local network / Tailscale',
-  'mode.official': 'Official relay (no server needed)',
+  'mode.official': 'Official relay',
   'mode.remote': 'Self-hosted relay',
-  'mode.local.description': 'The relay listens on 127.0.0.1. Only a browser on this machine can reach it.',
-  'mode.lan.description': 'The relay listens on 0.0.0.0 (every interface), so phones on your LAN or tailnet can reach it.',
-  'mode.official.description': 'Reach this machine from anywhere through the relay run by the Herdr Remote project. Nothing to deploy. Your terminal traffic passes through a server you do not control, and only devices you pair can open it.',
-  'mode.remote.description': 'No local relay. The workstation dials a relay you run, which is the only way in from outside your network.',
+  'mode.local.description': 'Relay listens on 127.0.0.1. Local browser only.',
+  'mode.lan.description': 'Relay listens on 0.0.0.0. Accessible over LAN or Tailscale.',
+  'mode.official.description': 'Connect via official relay. No server needed.',
+  'mode.remote.description': 'Connect via self-hosted relay for external access.',
 
   'overview.title': 'Status',
   'overview.mode': 'Access mode',
@@ -62,21 +62,21 @@ module.exports = {
   'overview.relayRemote': 'remote, {url}',
   'overview.socketMissing': 'not found — is Herdr running?',
   'overview.unreachable': 'unreachable: {message}',
-  'overview.notStarted': 'Services are not running. Open the Services tab to start them.',
+  'overview.notStarted': 'Services not running. Open Services tab to start.',
 
   'pair.title': 'Pair a device',
-  'pair.generate': 'Generate a one-time pairing code',
-  'pair.regenerate': 'Generate another code',
-  'pair.working': 'Starting services and requesting a code…',
+  'pair.generate': 'Generate pairing code',
+  'pair.regenerate': 'Regenerate code',
+  'pair.working': 'Generating pairing code…',
   'pair.code': 'Pairing code',
-  'pair.url': 'Open on your phone',
+  'pair.url': 'Access URL',
   'pair.expires': 'Expires in {minutes} (at {time})',
-  'pair.expired': 'This code has expired. Generate a new one.',
-  'pair.instructions': 'Open the URL, enter the code, and the browser is paired for good.',
-  'pair.qrHint': 'Scan the code with your phone camera to open the URL.',
-  'pair.qrUnavailable': 'The terminal is too narrow for a QR code; use the URL above.',
-  'pair.failed': 'Could not create a pairing code: {message}',
-  'pair.hostOffline': 'The relay has no workstation connected yet. Start the services first.',
+  'pair.expired': 'Code expired. Generate a new one.',
+  'pair.instructions': 'Open URL and enter code to pair.',
+  'pair.qrHint': 'Scan QR code to open URL.',
+  'pair.qrUnavailable': 'Terminal too narrow for QR code; use URL above.',
+  'pair.failed': 'Could not create pairing code: {message}',
+  'pair.hostOffline': 'Relay has no workstation connected. Start services first.',
 
   'services.title': 'Services',
   'services.start': 'Start services',
@@ -87,58 +87,61 @@ module.exports = {
   'services.restarted': 'Services restarted.',
   'services.startFailed': 'Could not start services: {message}',
   'services.stopFailed': 'Could not stop services: {message}',
-  'services.unsavedBlocked': 'There are unsaved changes. Save them first, or the services restart on the configuration still on disk.',
-  'services.managedNotice': 'These services are managed by {manager}; the keep-alive unit was used to apply the change.',
-  'services.logs': 'Recent log output',
-  'services.logEmpty': 'No log output yet.',
+  'services.unsavedBlocked': 'Unsaved changes. Save before restarting.',
+  'services.managedNotice': 'Managed by {manager}; applied via keep-alive service.',
+  'services.logs': 'Recent logs',
+  'services.logEmpty': 'No logs.',
   'services.logRelay': 'Relay',
   'services.logHost': 'Host connector',
 
   'relay.title': 'Relay settings',
   'relay.settings': 'Settings',
+  'relay.locked': 'fixed',
+  'relay.officialFixed': 'The official relay address is fixed and cannot be edited.',
+  'relay.officialHint': 'Official relay: address is fixed and no password is needed.',
   'relay.password': 'Relay password',
-  'relay.passwordHint': 'Must match RELAY_PASSWORD on the relay. Leave empty for a public relay.',
+  'relay.passwordHint': 'Must match RELAY_PASSWORD on relay. Leave empty if public.',
   'relay.passwordSet': 'set',
-  'relay.passwordEmpty': 'not set (public relay)',
-  'relay.passwordSaved': 'Relay password saved. Restart the services to apply it.',
-  'relay.showPassword': 'Show the password',
-  'relay.hidePassword': 'Hide the password',
-  'relay.identity': 'Workstation id',
-  'relay.regenerate': 'Generate a new workstation identity',
-  'relay.regenerated': 'New workstation identity generated. Restart the services to enrol again.',
-  'relay.envSnippet': 'Command for your relay server',
-  'relay.envHint': 'Run this on the relay host.',
-  'relay.test': 'Test the relay connection',
+  'relay.passwordEmpty': 'not set (public)',
+  'relay.passwordSaved': 'Relay password saved. Restart services to apply.',
+  'relay.showPassword': 'Show password',
+  'relay.hidePassword': 'Hide password',
+  'relay.identity': 'Workstation ID',
+  'relay.regenerate': 'Generate new ID',
+  'relay.regenerated': 'New workstation identity generated. Restart services to re-register.',
+  'relay.envSnippet': 'Relay startup command',
+  'relay.envHint': 'Run this command on the relay host.',
+  'relay.test': 'Test relay connection',
   'relay.testOk': 'Relay reachable: version {version}, {hosts} workstation(s) connected.',
   'relay.testFailed': 'Relay unreachable: {message}',
-  'relay.selectAddress': 'Choose the address to advertise',
+  'relay.selectAddress': 'Choose advertised address',
   'relay.listenAddress': 'Listen address',
-  'relay.listenAddressHint': 'This is the server bind address. The advertised address below is what browsers open.',
+  'relay.listenAddressHint': 'Server bind address. Browsers use advertised address below.',
   'relay.addressTailscale': 'Tailscale',
   'relay.addressLan': 'LAN',
   'relay.addressVirtual': 'virtual',
   'relay.addressLoopback': 'loopback',
-  'relay.noAddresses': 'No non-loopback addresses found. Connect to a network or start Tailscale.',
-  'relay.docsHint': 'Running your own relay: see docs/self-hosted-relay.md',
+  'relay.noAddresses': 'No non-loopback addresses found.',
+  'relay.docsHint': 'Self-hosting guide: docs/self-hosted-relay.md',
 
   'keepalive.title': 'Keep-alive service',
   'keepalive.manager': 'Manager',
   'keepalive.state': 'State',
   'keepalive.install': 'Install and start',
   'keepalive.uninstall': 'Stop and remove',
-  'keepalive.restart': 'Restart the service',
+  'keepalive.restart': 'Restart service',
   'keepalive.installed': 'Keep-alive installed with {manager}.',
   'keepalive.uninstalled': 'Keep-alive removed.',
   'keepalive.restarted': 'Keep-alive service restarted.',
   'keepalive.failed': 'Keep-alive operation failed: {message}',
   'keepalive.unitPath': 'Unit file',
-  'keepalive.logsHint': 'Follow logs with: {command}',
-  'keepalive.linger': 'Start at boot without logging in',
-  'keepalive.lingerEnabled': 'Lingering is enabled: the service starts at boot.',
-  'keepalive.lingerDisabled': 'Lingering is off, so the service only runs while you are logged in.',
+  'keepalive.logsHint': 'View logs: {command}',
+  'keepalive.linger': 'Start at boot',
+  'keepalive.lingerEnabled': 'Start at boot enabled.',
+  'keepalive.lingerDisabled': 'Start at boot disabled (runs while logged in).',
   'keepalive.enableLinger': 'Enable start at boot',
-  'keepalive.lingerDone': 'Lingering enabled for {username}.',
-  'keepalive.fallbackNote': 'No system service manager is available; a supervised background process is used instead. It does not survive a reboot.',
+  'keepalive.lingerDone': 'Start at boot enabled for {username}.',
+  'keepalive.fallbackNote': 'No system service manager found; background process will not survive reboot.',
 
   'herdr.title': 'Herdr integration',
   'herdr.socketPath': 'Socket path',
@@ -146,16 +149,16 @@ module.exports = {
   'herdr.plugin': 'Plugin registration',
   'herdr.pluginRegistered': 'Registered with Herdr.',
   'herdr.pluginMissing': 'Not registered with Herdr.',
-  'herdr.register': 'Register this package as a Herdr plugin',
-  'herdr.unregister': 'Unregister the Herdr plugin',
+  'herdr.register': 'Register as Herdr plugin',
+  'herdr.unregister': 'Unregister plugin',
   'herdr.registerDone': 'Registered: {path}',
   'herdr.unregisterDone': 'Plugin unregistered.',
   'herdr.registerFailed': 'Registration failed: {message}',
-  'herdr.cliMissing': 'The herdr command was not found on PATH.',
+  'herdr.cliMissing': 'Command herdr not found in PATH.',
 
   'about.title': 'Language & about',
   'about.language': 'Interface language',
-  'about.languageAuto': 'Follow the system ({detected})',
+  'about.languageAuto': 'Follow system ({detected})',
   'about.languageZh': '中文',
   'about.languageEn': 'English',
   'about.version': 'Version',
@@ -166,20 +169,20 @@ module.exports = {
 
   'wizard.title': 'First-time setup',
   'wizard.step': 'Step {current} of {total}',
-  'wizard.languageTitle': 'Choose your language',
-  'wizard.accessTitle': 'How do you want to reach this machine?',
-  'wizard.accessHint': 'You can change this later on the Relay screen.',
-  'wizard.addressTitle': 'Which address should phones use?',
-  'wizard.relayTitle': 'Your relay server',
+  'wizard.languageTitle': 'Choose language',
+  'wizard.accessTitle': 'Access mode',
+  'wizard.accessHint': 'Can be changed later in Relay settings.',
+  'wizard.addressTitle': 'Browser access address',
+  'wizard.relayTitle': 'Relay server',
   'wizard.relayUrlLabel': 'Relay URL (wss://…)',
-  'wizard.relayHint': 'The relay must already be running. See docs/self-hosted-relay.md to set one up.',
+  'wizard.relayHint': 'Relay must be running. See docs/self-hosted-relay.md.',
   'wizard.passwordTitle': 'Relay password',
-  'wizard.passwordHint': 'The RELAY_PASSWORD your relay was started with. Leave it empty if the relay has none.',
-  'wizard.finishTitle': 'Ready',
+  'wizard.passwordHint': 'RELAY_PASSWORD of the relay. Leave empty if unset.',
+  'wizard.finishTitle': 'Finish',
   'wizard.finishHint': 'Configuration will be saved to {path}.',
-  'wizard.startNow': 'Start the services now',
-  'wizard.installKeepalive': 'Keep the services running in the background',
-  'wizard.finish': 'Save and continue',
+  'wizard.startNow': 'Start services now',
+  'wizard.installKeepalive': 'Run in background',
+  'wizard.finish': 'Save and finish',
 
   'field.mode': 'Access mode',
   'field.port': 'Relay port',
@@ -195,15 +198,15 @@ module.exports = {
   'placeholder.none': 'none',
 
   'error.invalidMode': 'Unknown access mode.',
-  'error.invalidPort': 'The port must be a number between 1 and 65535.',
-  'error.invalidLanHost': 'The browser address must be a reachable LAN or Tailscale address, not loopback or 0.0.0.0.',
-  'error.invalidRelayUrl': 'The relay URL must start with wss://, ws://, https:// or http://.',
-  'error.invalidPublicUrl': 'The browser URL must start with https:// or http:// and cannot use 0.0.0.0 or ::.',
+  'error.invalidPort': 'Port must be a number between 1 and 65535.',
+  'error.invalidLanHost': 'Browser address must be a reachable LAN or Tailscale address, not loopback or 0.0.0.0.',
+  'error.invalidRelayUrl': 'Relay URL must start with wss://, ws://, https:// or http://.',
+  'error.invalidPublicUrl': 'Browser URL must start with https:// or http:// and cannot use 0.0.0.0 or ::.',
   'error.invalidLanguage': 'Unknown language.',
   'error.invalidKeepalive': 'Unknown keep-alive manager.',
   'error.unknownField': 'Unknown setting.',
-  'error.remoteUrlRequired': 'A relay URL is required for the self-hosted relay mode.',
-  'error.saveFailed': 'Could not save the configuration: {message}',
+  'error.remoteUrlRequired': 'Relay URL is required for self-hosted relay mode.',
+  'error.saveFailed': 'Could not save configuration: {message}',
 
   'hint.navigate': '↑↓ move',
   'hint.select': '↵ select',
@@ -214,20 +217,21 @@ module.exports = {
   'hint.mouseOn': 'm mouse off',
   'hint.mouseOff': 'm mouse on',
   'hint.mouseUnsupported': 'mouse unsupported',
-  'hint.restartRequired': 'Restart the services to apply these changes.',
-  'hint.unsavedChanges': 'Unsaved changes — press s to save.',
+  'hint.restartRequired': 'Restart services to apply changes.',
+  'hint.unsavedChanges': 'Unsaved changes (press s to save).',
   'hint.save': 's save',
   'hint.editing': '↵ confirm · esc cancel',
   'update.title': 'Updates',
   'update.check': 'Check for updates',
   'update.checking': 'Checking npm…',
   'update.upToDate': 'Up to date ({version})',
-  'update.available': 'Update available: {version} — press Enter to install',
+  'update.available': 'Update {version} available (press Enter to install)',
   'update.updating': 'Installing {version}…',
   'update.done': 'Updated to {version}',
-  'update.restartHint': 'Update installed. Restart herdr-remote to use it.',
-  'update.errorNetwork': 'Could not reach the npm registry',
-  'update.errorFailed': 'The update failed. Try: npm install -g herdr-remote@latest',
-  'update.cannot.source': 'Running from a source checkout — update with git, not npm',
-  'update.cannot.linked': 'Running from a linked working copy — npm link manages this one',
+  'update.restartHint': 'Update installed. Restart herdr-remote to apply.',
+  'update.errorNetwork': 'Could not reach any npm registry',
+  'update.errorNetworkDetail': 'No registry answered: {message}',
+  'update.errorFailed': 'Update failed. Run: npm install -g herdr-remote@latest',
+  'update.cannot.source': 'Source checkout — update with git',
+  'update.cannot.linked': 'Linked package — managed by npm link',
 };