herdr-remote 0.2.11 → 0.2.13

package/herdr-plugin.toml

@@ -1,7 +1,7 @@
 id = "herdr.remote.web"
 name = "Herdr Remote Web"
-version = "0.2.11"
-min_herdr_version = "0.9.0"
+version = "0.2.13"
+min_herdr_version = "0.9.1"
 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.11",
+  "version": "0.2.13",
   "description": "Browser access to Herdr workspaces: plugin, host connector, and configuration TUI",
   "license": "MIT",
   "repository": {

package/src/agent-status.js

@@ -0,0 +1,114 @@
+'use strict';
+
+/**
+ * What the agents on this workstation are doing, small enough to put in a
+ * status bar.
+ *
+ * The question a phone actually has is "does anything need me?", and the
+ * terminal is a poor way to ask it: finding a blocked agent means navigating
+ * Herdr's sidebar through a viewport the width of a hand. Herdr already knows
+ * the answer — it classifies every pane as idle, working, blocked, done or
+ * unknown — so this turns a session snapshot into the two-line version.
+ *
+ * Deliberately a pure function over a snapshot. The socket, the debounce and
+ * the retry live in the host connector; what counts as "needs me" lives here,
+ * where it can be tested without either.
+ */
+
+/** Herdr's own vocabulary, in the order a person cares about them. */
+const AGENT_STATUSES = ['blocked', 'done', 'working', 'idle', 'unknown'];
+
+/**
+ * How many agents travel with the summary.
+ *
+ * The counts are always exact; this caps only the named list, which exists so a
+ * future screen can say *which* agent is blocked. A workstation with more than
+ * this many live agents is not going to be read off a phone anyway.
+ */
+const MAX_LISTED_AGENTS = 16;
+
+/** Titles come from a remote program; keep them short and printable. */
+const MAX_TITLE_LENGTH = 48;
+
+function cleanText(value, limit = MAX_TITLE_LENGTH) {
+  if (typeof value !== 'string') return null;
+  // eslint-disable-next-line no-control-regex
+  const collapsed = value.replace(/[\u0000-\u001F\u007F-\u009F]/g, ' ').replace(/\s+/g, ' ').trim();
+  if (!collapsed) return null;
+  return collapsed.length > limit ? collapsed.slice(0, limit) : collapsed;
+}
+
+function normalizeStatus(value) {
+  return AGENT_STATUSES.includes(value) ? value : 'unknown';
+}
+
+function emptyCounts() {
+  return Object.fromEntries(AGENT_STATUSES.map((status) => [status, 0]));
+}
+
+/**
+ * Turn `session.snapshot` into the summary the browser receives.
+ *
+ * Sorted by how much each status wants attention, so the capped list keeps the
+ * agents worth naming rather than the first ones Herdr happened to report.
+ */
+function summarizeAgents(snapshot) {
+  const entries = Array.isArray(snapshot?.agents) ? snapshot.agents : [];
+  const counts = emptyCounts();
+  const ranked = [];
+
+  for (const entry of entries) {
+    if (!entry || typeof entry.pane_id !== 'string') continue;
+    const status = normalizeStatus(entry.agent_status);
+    counts[status] += 1;
+    ranked.push({
+      paneId: entry.pane_id,
+      workspaceId: typeof entry.workspace_id === 'string' ? entry.workspace_id : null,
+      agent: cleanText(entry.display_agent || entry.agent, 24),
+      title: cleanText(entry.terminal_title_stripped || entry.terminal_title),
+      status,
+      focused: entry.focused === true,
+    });
+  }
+
+  ranked.sort((left, right) => AGENT_STATUSES.indexOf(left.status) - AGENT_STATUSES.indexOf(right.status));
+
+  return {
+    counts,
+    // Total rather than a sum the browser has to compute, and the one number a
+    // collapsed chip can show on its own.
+    total: ranked.length,
+    agents: ranked.slice(0, MAX_LISTED_AGENTS),
+  };
+}
+
+/** Whether two summaries say the same thing, so an unchanged one is not sent. */
+function sameSummary(left, right) {
+  if (!left || !right) return left === right;
+  if (left.total !== right.total) return false;
+  for (const status of AGENT_STATUSES) {
+    if ((left.counts?.[status] || 0) !== (right.counts?.[status] || 0)) return false;
+  }
+  if (left.agents.length !== right.agents.length) return false;
+  return left.agents.every((agent, index) => {
+    const other = right.agents[index];
+    return other
+      && agent.paneId === other.paneId
+      && agent.status === other.status
+      && agent.agent === other.agent
+      && agent.title === other.title;
+  });
+}
+
+/** The summary of a workstation with nothing to report, or nothing to ask. */
+function emptySummary() {
+  return { counts: emptyCounts(), total: 0, agents: [] };
+}
+
+module.exports = {
+  AGENT_STATUSES,
+  MAX_LISTED_AGENTS,
+  emptySummary,
+  sameSummary,
+  summarizeAgents,
+};

package/src/herdr-api.js

@@ -0,0 +1,123 @@
+'use strict';
+
+/**
+ * One question for Herdr's local socket API.
+ *
+ * Everything else in this package talks to Herdr by spawning a client into a
+ * PTY and shipping the bytes. That is the terminal. This is the side channel:
+ * the one place that asks Herdr *about* itself rather than drawing it, so a
+ * phone can answer "does anything need me?" without navigating a TUI through a
+ * 40-column viewport.
+ *
+ * The wire format is newline-delimited JSON over the Unix socket:
+ *
+ *   request   {"id":"…","method":"session.snapshot","params":{}}
+ *   response  {"id":"…","result":{…}}  or  {"id":"…","error":{"code","message"}}
+ *
+ * One request per connection, which is why this is a function and not a client.
+ * Herdr closes the socket once it has answered: against 0.9.1 a second request
+ * written to the same connection meets `EPIPE`. A long-lived client that
+ * reconnects on close therefore turns into a connect-answer-close loop about
+ * once a second, busy regardless of how rarely it actually asks anything. The
+ * `herdr` CLI connects per command for the same reason, and so does this.
+ *
+ * Subscriptions are the exception Herdr does keep open — `events.subscribe`
+ * holds the connection — but they are no use here: the event that tracks agent
+ * state is scoped to a single `pane_id`, and the whole-session pane events stay
+ * silent through minutes of continuous agent work. The caller polls.
+ *
+ * Nothing here may affect a terminal session. Herdr's server is an ordinary
+ * process that can be restarted under a running herdr-remote, and when it is,
+ * the PTYs keep streaming while this quietly fails and is asked again later.
+ */
+
+const net = require('node:net');
+
+/** How long one question waits, connection included. */
+const REQUEST_TIMEOUT_MS = 10_000;
+
+/** An answer this long is not an answer. Guards a socket that never newlines. */
+const MAX_RESPONSE_BYTES = 8 * 1024 * 1024;
+
+let requestCounter = 0;
+
+/**
+ * Ask Herdr one thing.
+ *
+ * Resolves with the `result` object, rejects for a refused connection, a
+ * timeout, an unparseable answer, or an `error` response — in which case
+ * `error.code` is Herdr's own code.
+ */
+function requestHerdr(socketPath, method, params = {}, options = {}) {
+  const { timeout = REQUEST_TIMEOUT_MS, connect = net.connect } = options;
+  requestCounter += 1;
+  const id = `herdr-remote:${requestCounter}`;
+
+  return new Promise((resolve, reject) => {
+    let socket;
+    let buffer = '';
+    let settled = false;
+
+    const finish = (error, result) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      if (socket) {
+        socket.removeAllListeners();
+        socket.destroy();
+      }
+      if (error) reject(error);
+      else resolve(result);
+    };
+
+    const timer = setTimeout(
+      () => finish(new Error(`Herdr API did not answer ${method} in time`)),
+      timeout,
+    );
+    if (typeof timer.unref === 'function') timer.unref();
+
+    try {
+      socket = connect(socketPath);
+    } catch (error) {
+      finish(error);
+      return;
+    }
+
+    socket.setEncoding('utf8');
+    socket.on('connect', () => {
+      socket.write(`${JSON.stringify({ id, method, params })}\n`);
+    });
+    socket.on('data', (chunk) => {
+      buffer += chunk;
+      if (buffer.length > MAX_RESPONSE_BYTES) {
+        finish(new Error('Herdr API sent an oversized response'));
+        return;
+      }
+      const newline = buffer.indexOf('\n');
+      if (newline === -1) return;
+      let message;
+      try {
+        message = JSON.parse(buffer.slice(0, newline));
+      } catch {
+        finish(new Error('Herdr API sent a line that is not JSON'));
+        return;
+      }
+      if (message.error) {
+        const error = new Error(message.error.message || 'Herdr API request failed');
+        error.code = message.error.code || 'herdr_api_error';
+        finish(error);
+        return;
+      }
+      finish(null, message.result);
+    });
+    socket.on('error', (error) => finish(error));
+    // Herdr hanging up before it answered is the ordinary shape of "the server
+    // is not running", not something that needs its own diagnosis.
+    socket.on('close', () => finish(new Error(`Herdr API closed before answering ${method}`)));
+  });
+}
+
+module.exports = {
+  REQUEST_TIMEOUT_MS,
+  requestHerdr,
+};

package/src/herdr-command.js

@@ -18,9 +18,25 @@
 const fs = require('node:fs');
 const os = require('node:os');
 const path = require('node:path');
+const { spawnSync } = require('node:child_process');
+// The same MAJOR.MINOR.PATCH comparison the self-updater uses. A second copy
+// would be a second place for 0.9.10 to sort below 0.9.9.
+const { compareVersions } = require('./updater');
 
 const COMMAND_NAME = 'herdr';
 
+/**
+ * The oldest Herdr this release is written against.
+ *
+ * 0.9.0 gave every client its own view, which is what one PTY per browser
+ * window rests on. 0.9.1 is what makes that model behave: window titles follow
+ * each client's own view instead of another client's selection, activating a
+ * machine in the background stops resizing somebody else's focused pane, and a
+ * large paste no longer disconnects the client — and pasting is how an image
+ * reaches an agent from a phone.
+ */
+const MIN_HERDR_VERSION = '0.9.1';
+
 /** Where a user-level install lands, in the order we trust it. */
 const FALLBACK_DIRECTORIES = [
   '~/.local/bin',
@@ -138,6 +154,57 @@ function verifyHerdrCommand(command, options = {}) {
   return findHerdrCommand(options);
 }
 
+/** `herdr 0.9.1`, `herdr 0.10.0-preview.2` — the three numbers are all we compare. */
+function parseHerdrVersion(output) {
+  const match = /(\d+)\.(\d+)\.(\d+)/.exec(String(output || ''));
+  return match ? `${match[1]}.${match[2]}.${match[3]}` : null;
+}
+
+/**
+ * Whether an install is new enough.
+ *
+ * An unreadable version counts as new enough. Not knowing is not evidence of an
+ * old Herdr, and a warning nobody can act on is worse than no warning.
+ */
+function meetsMinimum(version, minimum = MIN_HERDR_VERSION) {
+  if (!version) return true;
+  return compareVersions(version, minimum) >= 0;
+}
+
+/**
+ * Ask an install what it is.
+ *
+ * Deliberately the binary and not the socket: `--version` answers before the
+ * server is up, which is when the TUI and the plugin registration ask.
+ *
+ * `ok` is whether the command ran at all — the presence check registration has
+ * always used. `version` is null whenever the output could not be read, and
+ * `supported` is true in that case for the reason `meetsMinimum` explains.
+ */
+function herdrVersion({ command, timeout = 10_000, ...lookup } = {}) {
+  const resolved = command || resolveHerdrCommand(lookup);
+  const unknown = { command: resolved, version: null, raw: null, supported: true, ok: false };
+  let result;
+  try {
+    result = spawnSync(resolved, ['--version'], { encoding: 'utf8', timeout });
+  } catch {
+    return unknown;
+  }
+  // Status 1 has always counted as present: a binary that answers at all is
+  // installed, whatever it thinks of the flag.
+  if (result.error || (result.status !== 0 && result.status !== 1)) return unknown;
+  const raw = `${result.stdout || ''}${result.stderr || ''}`.trim();
+  const version = parseHerdrVersion(raw);
+  return { command: resolved, version, raw: raw || null, supported: meetsMinimum(version), ok: true };
+}
+
+/** The one line that tells a user why an older Herdr is a problem here. */
+function herdrOutdatedMessage(version) {
+  return `Herdr ${version} is older than ${MIN_HERDR_VERSION}, which herdr-remote is written against. `
+    + 'Run "herdr update" — window titles, background machine activation and large pastes all '
+    + 'misbehave in browser windows before that release.';
+}
+
 /** 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();
@@ -151,9 +218,14 @@ function herdrNotFoundMessage({ env = process.env, home = os.homedir(), director
 module.exports = {
   COMMAND_NAME,
   FALLBACK_DIRECTORIES,
+  MIN_HERDR_VERSION,
   fallbackDirectories,
   findHerdrCommand,
   herdrNotFoundMessage,
+  herdrOutdatedMessage,
+  herdrVersion,
+  meetsMinimum,
+  parseHerdrVersion,
   resolveHerdrCommand,
   verifyHerdrCommand,
 };

package/src/herdr-plugin.js

@@ -10,7 +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 { herdrVersion, resolveHerdrCommand } = require('./herdr-command');
 
 const PLUGIN_ID = 'herdr.remote.web';
 const MANIFEST_NAME = 'herdr-plugin.toml';
@@ -23,8 +23,7 @@ function manifestPath() {
 // 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(resolveHerdrCommand(), ['--version'], { stdio: 'ignore' });
-  return result.status === 0 || result.status === 1;
+  return herdrVersion().ok;
 }
 
 function runHerdr(args, { timeout = 15_000 } = {}) {
@@ -68,6 +67,10 @@ function registrationStatus() {
   if (!fs.existsSync(manifestPath())) {
     return { available: false, registered: false, reason: 'manifest missing' };
   }
+  // Carried on every answer: the screen that shows registration is also the one
+  // that has to say the installed Herdr is too old for this plugin.
+  const { version, supported } = herdrVersion();
+  const installed = { version, versionSupported: supported };
   let result;
   try {
     result = runHerdr(['plugin', 'list']);
@@ -76,11 +79,11 @@ function registrationStatus() {
     throw error;
   }
   if (result.status !== 0) {
-    return { available: true, registered: false, reason: String(result.stderr || '').trim() };
+    return { available: true, registered: false, reason: String(result.stderr || '').trim(), ...installed };
   }
   const plugins = parsePluginList(result.stdout);
   const entry = plugins.find((plugin) => plugin.id === PLUGIN_ID);
-  if (!entry) return { available: true, registered: false, packageRoot: PACKAGE_ROOT };
+  if (!entry) return { available: true, registered: false, packageRoot: PACKAGE_ROOT, ...installed };
   return {
     available: true,
     registered: true,
@@ -90,6 +93,7 @@ function registrationStatus() {
     // switching from a source install to npm.
     stale: Boolean(entry.localPath) && path.resolve(entry.localPath) !== path.resolve(PACKAGE_ROOT),
     packageRoot: PACKAGE_ROOT,
+    ...installed,
   };
 }
 

package/src/host-connector.js

@@ -9,7 +9,13 @@ const { loadConfig, hostWebSocketUrl, resolveHostRelayUrl, stateDir } = require(
 const { ensureDir } = require('./state');
 const { resolveSocketPath, inspectSocket } = require('./socket-discovery');
 const { PtySession } = require('./pty-session');
-const { resolveHerdrCommand, verifyHerdrCommand, herdrNotFoundMessage } = require('./herdr-command');
+const {
+  resolveHerdrCommand,
+  verifyHerdrCommand,
+  herdrNotFoundMessage,
+  herdrOutdatedMessage,
+  herdrVersion,
+} = require('./herdr-command');
 // The wire format lives in the relay package so both ends of the protocol are
 // generated from one definition.
 const {
@@ -20,9 +26,14 @@ const {
   PROTOCOL_VERSION,
 } = require('herdr-remote-relay/protocol');
 const { resolveHostPalette } = require('./terminal-palette');
+const { requestHerdr } = require('./herdr-api');
+const { sameSummary, summarizeAgents } = require('./agent-status');
 const { EXIT_REPLACED, EXIT_AUTH_FAILED } = require('./exit-codes');
 const { savePastedFile, cleanPastedDir } = require('./pasted-files');
 
+/** How often the agent summary is re-read while a browser is watching. */
+const AGENT_STATUS_POLL_MS = 5_000;
+
 function randomId(prefix) {
   return `${prefix}-${crypto.randomBytes(9).toString('base64url')}`;
 }
@@ -36,6 +47,19 @@ function closeSocket(ws, reason = 'host connector stopping') {
   try { ws.close(1000, reason); } catch {}
 }
 
+function terminateSocket(ws) {
+  if (!ws || ws.readyState === WebSocket.CLOSED) return;
+  try {
+    if (typeof ws.terminate === 'function') {
+      ws.terminate();
+    } else if (typeof ws.destroy === 'function') {
+      ws.destroy();
+    } else if (typeof ws.close === 'function') {
+      ws.close();
+    }
+  } catch {}
+}
+
 function pidAlive(pid) {
   if (!Number.isInteger(pid) || pid <= 0) return false;
   try {
@@ -69,6 +93,8 @@ class HostConnector {
     // real environment unless a caller narrows it.
     this.herdrLookup = options.herdrLookup || {};
     this.herdrCommand = options.herdrCommand || resolveHerdrCommand(this.herdrLookup);
+    this.readHerdrVersion = options.readHerdrVersion || herdrVersion;
+    this.herdrVersionWarned = false;
     this.herdrArgs = options.herdrArgs || config.herdr.args;
     this.cwd = options.cwd || config.herdr.cwd;
     /**
@@ -85,9 +111,15 @@ class HostConnector {
     this.sessions = new Map();
     this.streamIndexToId = new Map();
     this.PtySession = options.PtySession || PtySession;
+    /** The side channel that answers "does anything need me?"; see startAgentStatus. */
+    this.requestHerdr = options.requestHerdr || requestHerdr;
+    this.agentStatusTimer = null;
+    this.agentStatusPending = false;
+    this.lastAgentSummary = null;
     this.fastFailures = 0;
     this.reconnectTimer = null;
     this.heartbeatTimer = null;
+    this.keepaliveTimer = null;
     this.reconnectAttempts = 0;
     this.clientCount = 0;
     this.legacyHeartbeat = false;
@@ -154,6 +186,8 @@ class HostConnector {
     this.stopping = true;
     if (this.reconnectTimer) clearTimeout(this.reconnectTimer);
     if (this.heartbeatTimer) clearInterval(this.heartbeatTimer);
+    this.stopKeepalive();
+    this.stopAgentStatus();
     this.reconnectTimer = null;
     this.heartbeatTimer = null;
     sendJson(this.ws, { type: 'host_shutdown' });
@@ -168,6 +202,7 @@ class HostConnector {
 
   connect() {
     if (this.stopping || (this.ws && [WebSocket.OPEN, WebSocket.CONNECTING].includes(this.ws.readyState))) return;
+    this.stopKeepalive();
     let ws;
     try {
       ws = new WebSocket(this.relayUrl);
@@ -208,6 +243,10 @@ class HostConnector {
       this.ws = null;
       if (this.heartbeatTimer) clearInterval(this.heartbeatTimer);
       this.heartbeatTimer = null;
+      this.stopKeepalive();
+      // Nothing to report to, so stop asking Herdr. A reconnect brings the
+      // watcher back with the relay's next client count.
+      this.stopAgentStatus();
       this.ready = false;
       this.clientCount = 0;
       this.legacyHeartbeat = false;
@@ -276,6 +315,7 @@ class HostConnector {
     if (message.type === 'host_ready') {
       this.ready = true;
       this.reconnectAttempts = 0;
+      this.startKeepalive();
       if (Object.hasOwn(message, 'clientCount')) {
         this.legacyHeartbeat = false;
         this.setClientCount(message.clientCount);
@@ -316,11 +356,32 @@ class HostConnector {
     const resolved = verifyHerdrCommand(this.herdrCommand, this.herdrLookup);
     if (resolved.found) {
       this.herdrCommand = resolved.command;
+      this.warnIfHerdrOutdated();
       return null;
     }
     return herdrNotFoundMessage(this.herdrLookup);
   }
 
+  /**
+   * Say once that the installed Herdr is older than this release expects.
+   *
+   * Never a refusal to start. An older Herdr still runs — it just misbehaves in
+   * ways a browser window notices — and the comment on `startSession` explains
+   * what a refused start does to a reconnecting browser.
+   */
+  warnIfHerdrOutdated() {
+    if (this.herdrVersionWarned) return;
+    const installed = this.readHerdrVersion({ command: this.herdrCommand });
+    if (installed.supported) {
+      // A version we could not read is checked again on the next session: the
+      // install may simply not have been finished writing.
+      if (installed.version) this.herdrVersionWarned = true;
+      return;
+    }
+    this.herdrVersionWarned = true;
+    process.stderr.write(`herdr-remote host connector: ${herdrOutdatedMessage(installed.version)}\n`);
+  }
+
   startSession(message) {
     const streamId = typeof message.streamId === 'string' ? message.streamId : message.clientId;
     if (!streamId) return;
@@ -460,6 +521,49 @@ class HostConnector {
     this.sendHeartbeat();
   }
 
+  startKeepalive() {
+    this.stopKeepalive();
+    if (!this.ws || this.stopping) return;
+    this.ws.isAlive = true;
+    const interval = this.config?.cleanup?.heartbeatIntervalMs || 30_000;
+    this.keepaliveTimer = setInterval(() => this.tickKeepalive(), interval);
+  }
+
+  stopKeepalive() {
+    if (this.keepaliveTimer) {
+      clearInterval(this.keepaliveTimer);
+      this.keepaliveTimer = null;
+    }
+  }
+
+  tickKeepalive() {
+    const ws = this.ws;
+    if (!ws || this.stopping) return;
+    if (ws.readyState === WebSocket.CLOSING) {
+      terminateSocket(ws);
+      return;
+    }
+    if (ws.readyState !== WebSocket.OPEN) return;
+
+    if (!ws.isAlive) {
+      terminateSocket(ws);
+      return;
+    }
+
+    ws.isAlive = false;
+    try {
+      if (typeof ws.ping === 'function') ws.ping();
+    } catch {}
+
+    if (this.clientCount <= 0 && !this.legacyHeartbeat) {
+      sendJson(ws, {
+        type: 'heartbeat',
+        load: {},
+        ptys: [],
+      });
+    }
+  }
+
   setClientCount(value) {
     const next = Number.isInteger(value) ? Math.max(0, value) : 0;
     if (next === this.clientCount && (next === 0 || this.heartbeatTimer)) return;
@@ -474,6 +578,63 @@ class HostConnector {
       this.heartbeatTimer = null;
       if (wasActive) this.sendHeartbeat(true);
     }
+    // Nobody watching, nothing to ask Herdr about itself.
+    if (next > 0) this.startAgentStatus();
+    else this.stopAgentStatus();
+  }
+
+  /**
+   * Watch what the agents on this workstation are doing.
+   *
+   * A side channel, on its own socket, alive only while a browser is attached.
+   * Herdr's server can be restarted underneath a running herdr-remote — the
+   * PTYs survive it — so every failure here is a retry, never anything a
+   * terminal session notices.
+   *
+   * Polled, and one connection per poll: Herdr answers a socket request and
+   * hangs up, and its only long-lived connection — a subscription — carries no
+   * event that tracks agent state without naming a pane. See `herdr-api.js`.
+   */
+  startAgentStatus() {
+    if (this.agentStatusTimer || this.stopping) return;
+    this.agentStatusTimer = setInterval(() => this.readAgentStatus(), AGENT_STATUS_POLL_MS);
+    if (typeof this.agentStatusTimer.unref === 'function') this.agentStatusTimer.unref();
+    this.readAgentStatus();
+  }
+
+  stopAgentStatus() {
+    if (this.agentStatusTimer) {
+      clearInterval(this.agentStatusTimer);
+      this.agentStatusTimer = null;
+    }
+    this.lastAgentSummary = null;
+  }
+
+  /**
+   * Read the summary and forward it if it changed.
+   *
+   * A slow answer must not stack up behind the next tick, and a failed one
+   * leaves the last summary standing rather than blanking the browser's chip:
+   * Herdr's server not running is an ordinary state, not news.
+   */
+  async readAgentStatus() {
+    if (this.agentStatusPending || !this.agentStatusTimer) return;
+    this.agentStatusPending = true;
+    let snapshot;
+    try {
+      const result = await this.requestHerdr(this.socketPath, 'session.snapshot', {});
+      snapshot = result?.snapshot || result;
+    } catch {
+      return;
+    } finally {
+      this.agentStatusPending = false;
+    }
+    // Stopped while the answer was in flight; the browser it was for is gone.
+    if (!this.agentStatusTimer) return;
+    const summary = summarizeAgents(snapshot);
+    if (sameSummary(this.lastAgentSummary, summary)) return;
+    this.lastAgentSummary = summary;
+    sendJson(this.ws, { type: 'agent_status', ...summary });
   }
 
   resizeSession(message) {

package/src/i18n/en.js

@@ -155,6 +155,8 @@ module.exports = {
   'herdr.unregisterDone': 'Plugin unregistered.',
   'herdr.registerFailed': 'Registration failed: {message}',
   'herdr.cliMissing': 'Command herdr not found. Set HERDR_BIN_PATH to its full path.',
+  'herdr.version': 'Herdr version',
+  'herdr.versionOutdated': 'Herdr {version} is older than {minimum}. Run "herdr update": window titles, background machine activation and large pastes misbehave in browser windows before that release.',
 
   'about.title': 'Language & about',
   'about.language': 'Interface language',

package/src/i18n/zh.js

@@ -154,6 +154,8 @@ module.exports = {
   'herdr.unregisterDone': '已取消注册。',
   'herdr.registerFailed': '注册失败：{message}',
   'herdr.cliMissing': '未找到 herdr 命令，可将 HERDR_BIN_PATH 设为其完整路径。',
+  'herdr.version': 'Herdr 版本',
+  'herdr.versionOutdated': 'Herdr {version} 低于 {minimum}，请运行 “herdr update”：在该版本之前，浏览器窗口的标题、后台机器激活与大段粘贴都会出问题。',
 
   'about.title': '语言与关于',
   'about.language': '界面语言',