@andrian.yablonskyy/thub-coordinator 1.0.8 → 1.0.10

package/README.md

@@ -35,6 +35,7 @@ The Coordinator loads a plain **JSON** config file (no YAML support). Resolution
 {
   "listen": "127.0.0.1:8080",
   "publicUrl": "https://thub.example.com",
+  "trustProxy": "loopback",
   "dataDir": "/var/lib/thub",
   "sessionSecret": "change-me-to-a-long-random-string",
   "clientJoinKey": "change-me-to-a-long-random-string",
@@ -42,11 +43,12 @@ The Coordinator loads a plain **JSON** config file (no YAML support). Resolution
   "scheduler": { "assignAckTimeoutSec": 15, "requeueOnLost": true, "maxQueuedPerAgent": 20, "tickIntervalSec": 10 },
   "jobs": { "defaultTimeoutSec": 1800, "maxTimeoutSec": 14400 },
   "retention": { "logRetentionDays": 14, "artifactRetentionDays": 30 },
-  "artifacts": { "maxUploadMb": 512, "linkTtlHours": 168 }
+  "artifacts": { "maxUploadMb": 512, "linkTtlHours": 168 },
+  "updates": { "checkIntervalHours": 6, "registry": null }
 }
 ```
 
-`sessionSecret` signs the dashboard's session cookie and the HMAC on artifact download links; `clientJoinKey` is the shared secret Clients self-register with — omit or leave `null` to disable auto-registration entirely. Individual `THUB_LISTEN` / `THUB_PUBLIC_URL` / `THUB_DATA_DIR` / `THUB_SESSION_SECRET` / `THUB_CLIENT_JOIN_KEY` env vars override whatever the file set.
+`sessionSecret` signs the dashboard's session cookie and the HMAC on artifact download links; `clientJoinKey` is the shared secret Clients self-register with — omit or leave `null` to disable auto-registration entirely. `trustProxy` is Express's [`trust proxy`](https://expressjs.com/en/guide/behind-proxies.html) setting (default `loopback`): which reverse proxies' `X-Forwarded-For` to believe for a Client's external address on the resource card — e.g. `"10.0.0.0/8"` or `1` for a proxy on another host, `false` to always use the socket address. Individual `THUB_LISTEN` / `THUB_PUBLIC_URL` / `THUB_DATA_DIR` / `THUB_SESSION_SECRET` / `THUB_CLIENT_JOIN_KEY` env vars override whatever the file set.
 
 `npm install -g` creates `~/.config/thub/coordinator.json` for you if it doesn't already exist, with all the options above, `dataDir` set to `~/var/lib/thub` and a freshly generated random `sessionSecret` (not the placeholder above), readable only by its owner — a re-install never overwrites it or regenerates the secret. Set `publicUrl` and `clientJoinKey` yourself before relying on auto-registration.
 
@@ -99,13 +101,17 @@ thub-admin jobs clean --yes
 thub-admin group add ci-nightly --comment "shared CI pool"
 thub-admin group list
 thub-admin group remove <groupId>
+
+# The Coordinator is only ever updated by hand (never from the dashboard).
+thub-admin check-update                  # installed vs latest published version
+thub-admin self-update [--to <x.y.z>]    # sudo npm i -g; the postinstall restarts the service
 ```
 
 Both `jobs reset` and `jobs clean` refuse to run without `--yes` — there's no undo for either, especially `clean`.
 
 ## API
 
-All endpoints are under `/api/v1`, JSON, and require `Authorization: Bearer <token>` (the dashboard is a separate session-based auth path).
+All endpoints are under `/api/v1`, JSON, and require `Authorization: Bearer <token>` (the dashboard is a separate session-based auth path). The Agent and Client send `User-Agent: thub-agent/<version>` / `thub-client/<version>`, and the Coordinator records that version for the dashboard.
 
 **Agent endpoints** (used by [thub-agent](https://github.com/andrianyablonskyy/thub-agent)):
 
@@ -119,13 +125,14 @@ All endpoints are under `/api/v1`, JSON, and require `Authorization: Bearer <tok
 | `GET` | `/jobs/:id/logs/stream` | Server-Sent Events: `log`, `state`, `end`. Honors `Last-Event-ID` for resume. |
 | `GET` | `/jobs/:id/artifacts` | Artifact list with signed download URLs. |
 | `GET` | `/resources` | Resources with status (read-only). |
+| `GET` | `/agents/me/update` | `{updateTo, latest}` — a self-update requested for the calling agent. |
 
 **Resource (Client) endpoints** (used by [thub-client](https://github.com/andrianyablonskyy/thub-client)):
 
 | Method | Path | Description |
 |---|---|---|
-| `POST` | `/resources/register` | Self-register (every start/restart) using the shared `clientJoinKey`; upserts by `clientId`. |
-| `POST` | `/resources/:id/heartbeat` | Heartbeat and self-reported state; response may carry `commands[]`. |
+| `POST` | `/resources/register` | Self-register (every start/restart) using the shared `clientJoinKey`; upserts by `clientId`. `hostInfo.addresses` (`[{iface, address, family}]`) lists the host's non-loopback interface addresses; the request's source address is stored as the external one. |
+| `POST` | `/resources/:id/heartbeat` | Heartbeat and self-reported state, plus the current `addresses`; refreshes the external address; response may carry `commands[]` (`cancel-job`, `self-update`). |
 | `POST` | `/resources/:id/status` | Explicit status change, e.g. a local lock. |
 | `GET` | `/resources/:id/jobs/next?wait=30` | Long-poll for an assigned job; `204` when nothing arrived within `wait` seconds. |
 | `POST` | `/jobs/:id/accept` | Acknowledge assignment. |
@@ -142,14 +149,25 @@ Server-rendered Pug templates styled with Bootstrap 5.3, with a little vanilla J
 
 | Page | Content |
 |---|---|
-| `/` | Resource cards by status, queue length, jobs in the last 24 h. |
-| `/resources` | Type, labels, groups, status, busy source/reason, last heartbeat age; admin maintenance/rotate-token actions. |
+| `/` | Resource cards by status, queue length, jobs in the last 24 h. Click a card for its resource card (below). |
+| `/resources` | Type, Client version, labels, groups, status, busy source/reason, last heartbeat age; admin maintenance/rotate-token actions. Click a row for its resource card (below). |
 | `/groups` | Resource groups — id/name/comment, member count; admin create/rename/delete. Membership itself is set per-resource in the Client's own config. |
 | `/jobs` | Filterable job list (state, source, resource), with the job's `user` label if set; admin **Reset queue** / **Clean history**. |
 | `/jobs/:id` | Spec, timeline, live log viewer with stream filter, artifact downloads, cancel button. |
-| `/admin/agents` | Register/revoke CI and developer agents; token shown once. |
+| `/admin/agents` | Register/revoke CI and developer agents; token shown once. Shows each agent's last reported version. |
 | `/profile` | Every logged-in user's own account settings: display name, avatar, timezone (renders every dashboard timestamp), theme, idle session timeout, password change. |
 
+**Resource card.** Clicking a resource on `/` or `/resources` opens a card with its name, type, status, Client version, IP addresses, labels, groups, busy source/reason, last heartbeat and (admins only) the maintenance/rotate-token actions. IP addresses are the Client host's interface addresses except loopback (reported at registration and on every heartbeat) plus the external address — the one the Coordinator last saw the Client connect from, taken from `X-Forwarded-For` when the request came through a proxy `trustProxy` trusts.
+
+The Coordinator's own version (`ver. X.Y.Z`) is shown under the TestHub logo, top left of every page.
+
+**Versions and self-update.** The Coordinator checks the npm registry for the latest Coordinator, Agent and Client every `updates.checkIntervalHours` (default 6, `0` disables; `updates.registry` for a private mirror) and on **Check for updates**. A newer Coordinator shows as a badge under the logo; Agents and Resources show each one's version with an **update available** or pending **→ vX.Y.Z** badge. Admins request self-updates per agent/resource (**Update**, which becomes **Cancel update**) or with **Update all agents** / **Update all clients**, always to the latest version:
+- Clients get a `self-update` command on their next heartbeat and install it through their root `thub-client-update` helper, once none of the host's instances is busy.
+- Agents install it at the start of their next run (`GET /api/v1/agents/me/update`), then re-run the command on the new version.
+- The Coordinator itself is updated by hand only: `thub-admin self-update`.
+
+A request is cleared when the Agent/Client reports the new version.
+
 ## Data storage
 
 SQLite via `better-sqlite3`, WAL mode. Schema migrations are plain numbered SQL files in `src/db/migrations/`, applied automatically at startup. `job_logs` rows are compacted into `artifacts/<jobId>/console.log` when a job finishes and deleted after `logRetentionDays`; artifacts are deleted after `artifactRetentionDays`. See the [main repo's ER diagram](https://github.com/andrianyablonskyy/thub#9-data-storage-sqlite) for the full schema.

package/bin/thub-admin.js

@@ -32,7 +32,10 @@ const { loadConfig } = require('../src/config'),
   { createAdminUsersService } = require('../src/services/admin-users'),
   { createArtifactsService } = require('../src/services/artifacts'),
   { createJobsService } = require('../src/services/jobs'),
-  { generateToken } = require('../src/services/tokens');
+  { generateToken } = require('../src/services/tokens'),
+  { PACKAGES, fetchLatestVersion, isNewer, isValidVersion, npmBin } = require('@andrian.yablonskyy/thub-common'),
+  { spawnSync } = require('node:child_process'),
+  { version: installedVersion } = require('../package.json');
 
 function usage(){
   console.log(`Usage:
@@ -45,6 +48,9 @@ function usage(){
   thub-admin group add <name> [--comment <text>]
   thub-admin group list
   thub-admin group remove <groupId>
+  thub-admin check-update         Compare this Coordinator with the latest published version
+  thub-admin self-update [--to X.Y.Z]
+                                  Update this Coordinator (sudo npm i -g; restarts the service)
 `);
 }
 
@@ -79,9 +85,46 @@ function parseFlags(args){
   return { positional, flags };
 }
 
+// The Coordinator is only ever updated by hand (README §10.2) — never
+// from the dashboard. Neither command needs the database.
+async function updateCommand(cmd, args){
+  const { flags } = parseFlags(args),
+    latest = await fetchLatestVersion(PACKAGES.coordinator);
+  if (cmd === 'check-update'){
+    console.log(`Installed: v${installedVersion}  Latest: v${latest}`);
+    console.log(isNewer(latest, installedVersion) ? 'Update available: thub-admin self-update' : 'Up to date.');
+    return 0;
+  }
+  const target = flags.to || latest;
+  if (!isValidVersion(target)){
+    console.error(`Invalid version "${target}"`);
+    return 4;
+  }
+  if (!flags.to && !isNewer(target, installedVersion)){
+    console.log(`Already on v${installedVersion} (latest v${latest}).`);
+    return 0;
+  }
+  // Root, via sudo, so the postinstall re-renders and restarts the
+  // thub-coordinator service for the right user (SUDO_USER).
+  const npmArgs = ['i', '-g', `${PACKAGES.coordinator}@${target}`],
+    isRoot = process.getuid?.() === 0,
+    [bin, argv] = isRoot ? [npmBin(), npmArgs] : ['sudo', [npmBin(), ...npmArgs]];
+  console.log(`Updating Coordinator v${installedVersion} -> v${target}: ${[bin, ...argv].join(' ')}`);
+  return spawnSync(bin, argv, { stdio: 'inherit' }).status ?? 1;
+}
+
 function main(){
-  const [, , cmd, sub, ...rest] = process.argv,
-    config = loadConfig(),
+  const [, , cmd, sub, ...rest] = process.argv;
+  if (cmd === 'check-update' || cmd === 'self-update'){
+    return updateCommand(cmd, [sub, ...rest].filter(Boolean))
+      .then((code) => process.exit(code))
+      .catch((err) => {
+        console.error(`Error: ${err.message}`);
+        process.exit(1);
+      });
+  }
+
+  const config = loadConfig(),
     db = openDb(config.dbPath),
     events = createEventsService(db),
     registry = createRegistryService(db, { bus, events }),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@andrian.yablonskyy/thub-coordinator",
-  "version": "1.0.8",
+  "version": "1.0.10",
   "description": "TestHub Coordinator — job queue, resource registry, scheduler, heartbeat monitor, log/artifact store and web dashboard",
   "main": "src/server.js",
   "engines": {

package/public/js/resource-card.js

@@ -0,0 +1,38 @@
+/**
+ * @file        packages/coordinator/public/js/resource-card.js
+ * @description Dashboard: opens a resource's info card (modal) when its row/card is clicked or activated by keyboard
+ *
+ * @author      Andrian Yablonskyy
+ * @copyright   Copyright (c) 2026 Andrian Yablonskyy. All rights reserved.
+ *
+ * This file is part of TestHub and is proprietary and confidential.
+ * Unauthorized copying, modification, distribution, or use of this file,
+ * via any medium, is strictly prohibited without prior written permission
+ * from AdSystem.PRO.
+ */
+
+'use strict';
+
+(function (){
+  function open(el){
+    const modal = document.getElementById(el.dataset.resourceCard);
+    if (modal){
+      bootstrap.Modal.getOrCreateInstance(modal).show();
+    }
+  }
+
+  document.querySelectorAll('[data-resource-card]').forEach((el) => {
+    el.addEventListener('click', (e) => {
+      // The Resources table's own action buttons stay plain actions.
+      if (!e.target.closest('form, button, a, input')){
+        open(el);
+      }
+    });
+    el.addEventListener('keydown', (e) => {
+      if ((e.key === 'Enter' || e.key === ' ') && e.target === el){
+        e.preventDefault();
+        open(el);
+      }
+    });
+  });
+})();

package/src/api/agent.js

@@ -92,6 +92,14 @@ function createAgentRouter({ services, config }){
     res.json({ resources: services.registry.list().map(publicResource) });
   });
 
+  // Checked by the Agent at the start of every run (README §10.2): the
+  // version an admin asked it to self-update to, if still newer than the
+  // one it runs (auth has already recorded that from its User-Agent).
+  router.get('/agents/me/update', auth, (req, res) => {
+    const agent = services.agents.get(req.agent.id);
+    res.json({ updateTo: agent.update_to || null, latest: services.updates.status().latest.agent || null });
+  });
+
   return router;
 }
 

package/src/api/resource.js

@@ -15,7 +15,7 @@
 
 const express = require('express'),
   multer = require('multer'),
-  { requireRole, requireJoinKey } = require('../auth'),
+  { requireRole, requireJoinKey, appVersion } = require('../auth'),
   { JOB_STATES } = require('@andrian.yablonskyy/thub-common');
 
 const upload = multer({ dest: require('node:os').tmpdir() });
@@ -64,7 +64,9 @@ function createResourceRouter({ services, config }){
         type,
         labels: labels || capabilities?.labels || [],
         groups: groups || [],
-        hostInfo
+        hostInfo,
+        remoteAddr: req.ip,
+        clientVersion: appVersion(req, 'client')
       });
       res.json({ resourceId, resourceToken, heartbeatIntervalSec: config.heartbeat.intervalSec });
     }
@@ -81,9 +83,23 @@ function createResourceRouter({ services, config }){
 
   router.post('/resources/:id/heartbeat', auth, requireOwnResource, (req, res, next) => {
     try {
-      const { state, activeJobId, localLock, metrics } = req.body;
-      services.registry.heartbeat(req.params.id, { state, activeJobId, localLock, metrics });
-      const commands = services.commands.drain(req.params.id);
+      const { state, activeJobId, localLock, metrics, addresses } = req.body;
+      services.registry.heartbeat(req.params.id, {
+        state,
+        activeJobId,
+        localLock,
+        metrics,
+        addresses,
+        remoteAddr: req.ip,
+        clientVersion: appVersion(req, 'client')
+      });
+      const commands = services.commands.drain(req.params.id),
+        // Repeated on every heartbeat until the Client reports the new
+        // version (README §10.2) — the Client ignores repeats itself.
+        updateTo = services.registry.pendingUpdate(req.params.id);
+      if (updateTo){
+        commands.push({ command: 'self-update', version: updateTo });
+      }
       res.json({ serverTime: new Date().toISOString(), commands });
     }
     catch (err){

package/src/auth.js

@@ -17,6 +17,13 @@ const crypto = require('node:crypto'),
   { hashToken } = require('./services/tokens');
 
 // §3.1 / §12: bearer tokens are hashed with SHA-256 and carry a role
+// App version from a "thub-<app>/<version>" User-Agent (shared ApiClient),
+// or null for anything else (curl, an older Agent/Client).
+function appVersion(req, app){
+  const m = new RegExp(`^thub-${app}/([0-9A-Za-z.+-]{1,32})(?:\\s|$)`).exec(req.get('user-agent') || '');
+  return m ? m[1] : null;
+}
+
 // (agent | resource); admin is authenticated via the dashboard session
 // instead of an API token (§10).
 function requireRole(role){
@@ -33,7 +40,7 @@ function requireRole(role){
       if (!agent){
         return res.status(401).json({ error: 'Invalid or revoked agent token' });
       }
-      req.app.locals.services.agents.touchLastUsed(agent.id);
+      req.app.locals.services.agents.touchLastUsed(agent.id, appVersion(req, 'agent'));
       req.agent = agent;
       return next();
     }
@@ -91,4 +98,4 @@ function requireAdminRole(req, res, next){
   next();
 }
 
-module.exports = { requireRole, requireJoinKey, requireAdminSession, requireAdminRole };
+module.exports = { requireRole, requireJoinKey, requireAdminSession, requireAdminRole, appVersion };

package/src/config.js

@@ -21,6 +21,10 @@ const fs = require('node:fs'),
 const DEFAULTS = {
   listen: '127.0.0.1:8080',
   publicUrl: 'http://localhost:8080',
+  // Express `trust proxy`: which proxies' X-Forwarded-For to believe for
+  // a Client's external address (resource card). 'loopback' fits the
+  // default setup — listening on 127.0.0.1 behind a local reverse proxy.
+  trustProxy: 'loopback',
   dataDir: path.join(process.cwd(), '.data'),
   sessionSecret: 'dev-only-change-me',
   // Shared secret Clients present to self-register (see api/resource.js).
@@ -48,6 +52,13 @@ const DEFAULTS = {
   artifacts: {
     maxUploadMb: 512,
     linkTtlHours: 168
+  },
+  // New-version check of the Coordinator/Agent/Client packages (README
+  // §10.2). 0 disables the periodic check; registry null = the public npm
+  // registry (or npm_config_registry).
+  updates: {
+    checkIntervalHours: 6,
+    registry: null
   }
 };
 

package/src/db/migrations/008_add_remote_addr.sql

@@ -0,0 +1,5 @@
+-- Address the Coordinator last saw this resource's Client connect from
+-- (register or heartbeat) — its external IP from the Coordinator's point
+-- of view, shown on the dashboard's resource card next to the Client's own
+-- interface addresses (host_info.addresses).
+ALTER TABLE resources ADD COLUMN remote_addr TEXT;

package/src/db/migrations/009_add_app_versions.sql

@@ -0,0 +1,5 @@
+-- App version each Agent / Client last reported (User-Agent header
+-- "thub-agent/<version>" / "thub-client/<version>"), shown on the
+-- dashboard's Agents page and resource card (README §10).
+ALTER TABLE agents ADD COLUMN version TEXT;
+ALTER TABLE resources ADD COLUMN client_version TEXT;

package/src/db/migrations/010_add_update_to.sql

@@ -0,0 +1,5 @@
+-- Self-update requests (README §10.2): the version an admin asked this
+-- Agent / Client to update to, cleared once it reports that version (or
+-- newer). NULL = no update pending.
+ALTER TABLE agents ADD COLUMN update_to TEXT;
+ALTER TABLE resources ADD COLUMN update_to TEXT;

package/src/server.js

@@ -34,6 +34,7 @@ const path = require('node:path'),
   { createArtifactsService } = require('./services/artifacts'),
   { createCommandsService } = require('./services/commands'),
   { createRetentionService } = require('./services/retention'),
+  { createUpdatesService } = require('./services/updates'),
 
   { createAgentRouter } = require('./api/agent'),
   { createResourceRouter } = require('./api/resource'),
@@ -53,9 +54,11 @@ function buildServices(config){
     jobs = createJobsService(db, { bus, events, registry, artifacts, config }),
     scheduler = createScheduler(db, { bus, events, registry, config }),
     heartbeatMonitor = createHeartbeatMonitor(db, { bus, events, registry, jobs, config }),
-    retention = createRetentionService(db, { bus, logs, artifacts, config });
+    retention = createRetentionService(db, { bus, logs, artifacts, config }),
+    updates = createUpdatesService({ config });
 
   jobs.reconcileOnStartup();
+  updates.start();
 
   const sweepInterval = setInterval(() => {
     jobs.checkAssignAcks();
@@ -77,7 +80,8 @@ function buildServices(config){
     artifacts,
     scheduler,
     heartbeatMonitor,
-    retention
+    retention,
+    updates
   };
 }
 
@@ -85,7 +89,10 @@ function createApp(config, services){
   const app = express();
   app.set('view engine', 'pug');
   app.set('views', path.join(__dirname, '..', 'views'));
+  app.set('trust proxy', config.trustProxy);
   app.locals.services = services;
+  // Shown in every dashboard page's footer (layout.pug).
+  app.locals.coordinatorVersion = require('../package.json').version;
 
   app.use(express.json({ limit: '2mb' }));
   app.use(express.urlencoded({ extended: true }));

package/src/services/agents.js

@@ -13,7 +13,8 @@
 
 'use strict';
 
-const { v4: uuid } = require('uuid'),
+const { compareVersions } = require('@andrian.yablonskyy/thub-common'),
+  { v4: uuid } = require('uuid'),
   { generateToken, hashToken } = require('./tokens');
 
 function createAgentsService(db, { events }){
@@ -28,7 +29,7 @@ function createAgentsService(db, { events }){
   }
 
   function list(){
-    return db.prepare('SELECT id, name, kind, created_at, last_used_at, revoked_at FROM agents ORDER BY created_at DESC').all();
+    return db.prepare('SELECT id, name, kind, version, update_to, created_at, last_used_at, revoked_at FROM agents ORDER BY created_at DESC').all();
   }
 
   function create({ name, kind }){
@@ -46,11 +47,39 @@ function createAgentsService(db, { events }){
     events.record('agent', id, 'agent.revoked', {});
   }
 
-  function touchLastUsed(id){
-    db.prepare('UPDATE agents SET last_used_at = ? WHERE id = ?').run(new Date().toISOString(), id);
+  // `version` only when the Agent reported one — keeps the last known one
+  // otherwise. Reporting the requested update's version (or newer) is what
+  // completes a self-update request.
+  function touchLastUsed(id, version = null){
+    db.prepare('UPDATE agents SET last_used_at = ?, version = COALESCE(?, version) WHERE id = ?').run(new Date().toISOString(), version, id);
+    const agent = get(id);
+    if (agent?.update_to && agent.version && compareVersions(agent.version, agent.update_to) >= 0){
+      db.prepare('UPDATE agents SET update_to = NULL WHERE id = ?').run(id);
+      events.record('agent', id, 'agent.updated', { version: agent.version });
+    }
   }
 
-  return { get, getByTokenHash, list, create, revoke, touchLastUsed };
+  // Self-update request (README §10.2): the Agent picks it up on its next
+  // run. `version` null cancels a pending one.
+  function setUpdateTo(id, version){
+    const agent = get(id);
+    if (!agent || agent.revoked_at){
+      throw Object.assign(new Error('Unknown or revoked agent'), { status: 404 });
+    }
+    db.prepare('UPDATE agents SET update_to = ? WHERE id = ?').run(version, id);
+    events.record('agent', id, version ? 'agent.update_requested' : 'agent.update_canceled', { version });
+  }
+
+  // Every active agent not already on `version` or newer.
+  function requestUpdateAll(version){
+    const ids = db.prepare('SELECT id, version FROM agents WHERE revoked_at IS NULL').all()
+      .filter((a) => !a.version || compareVersions(a.version, version) < 0)
+      .map((a) => a.id);
+    ids.forEach((id) => setUpdateTo(id, version));
+    return ids.length;
+  }
+
+  return { get, getByTokenHash, list, create, revoke, touchLastUsed, setUpdateTo, requestUpdateAll };
 }
 
 module.exports = { createAgentsService };

package/src/services/registry.js

@@ -14,7 +14,7 @@
 'use strict';
 
 const { v4: uuid } = require('uuid'),
-  { RESOURCE_STATES, BUSY_SOURCES } = require('@andrian.yablonskyy/thub-common'),
+  { RESOURCE_STATES, BUSY_SOURCES, compareVersions } = require('@andrian.yablonskyy/thub-common'),
   { generateToken, hashToken } = require('./tokens');
 
 function rowToResource(row){
@@ -29,6 +29,28 @@ function rowToResource(row){
   };
 }
 
+// host_info.addresses comes straight from the Client, so keep only
+// well-formed { iface, address, family } entries and cap the list.
+const MAX_ADDRESSES = 64;
+function sanitizeAddresses(addresses){
+  if (!Array.isArray(addresses)){
+    return undefined;
+  }
+  return addresses
+    .filter((a) => a && typeof a.address === 'string' && /^[0-9A-Fa-f:.%\w-]{2,64}$/.test(a.address))
+    .slice(0, MAX_ADDRESSES)
+    .map((a) => ({
+      iface: typeof a.iface === 'string' ? a.iface.slice(0, 64) : '',
+      address: a.address,
+      family: a.family === 'IPv6' ? 'IPv6' : 'IPv4'
+    }));
+}
+
+// Express reports IPv4 clients of a dual-stack socket as ::ffff:a.b.c.d.
+function normalizeRemoteAddr(addr){
+  return typeof addr === 'string' && addr ? addr.replace(/^::ffff:(\d+\.\d+\.\d+\.\d+)$/, '$1') : null;
+}
+
 function createRegistryService(db, { bus, events }){
   function get(id){
     return rowToResource(db.prepare('SELECT * FROM resources WHERE id = ?').get(id));
@@ -84,8 +106,10 @@ function createRegistryService(db, { bus, events }){
   // this registration is allowed to reclaim it. Anything else (IDLE, BUSY,
   // MAINTENANCE, REGISTERED-but-just-created) means a process might still
   // be actively using that identity, so it stays a hard conflict.
-  function registerAuto({ clientId, name, type, labels = [], groups = [], hostInfo }){
-    const resourceToken = generateToken('res');
+  function registerAuto({ clientId, name, type, labels = [], groups = [], hostInfo, remoteAddr, clientVersion = null }){
+    const resourceToken = generateToken('res'),
+      remote = normalizeRemoteAddr(remoteAddr);
+    hostInfo = { ...(hostInfo || {}), addresses: sanitizeAddresses(hostInfo?.addresses) || [] };
     let existing = getByClientId(clientId);
 
     if (!existing){
@@ -133,7 +157,7 @@ function createRegistryService(db, { bus, events }){
       db.prepare(
         `UPDATE resources
          SET token_hash = ?, client_id = ?, name = ?, type = ?, labels = ?, group_ids = ?, host_info = ?,
-             status = ?, busy_source = NULL, busy_reason = NULL
+             remote_addr = ?, client_version = ?, status = ?, busy_source = NULL, busy_reason = NULL
          WHERE id = ?`
       ).run(
         hashToken(resourceToken),
@@ -142,11 +166,14 @@ function createRegistryService(db, { bus, events }){
         type,
         JSON.stringify(labels),
         JSON.stringify(groups),
-        JSON.stringify(hostInfo || {}),
+        JSON.stringify(hostInfo),
+        remote,
+        clientVersion,
         nextStatus,
         existing.id
       );
 
+      completeUpdateIfDone(existing.id);
       events.record('resource', existing.id, 'resource.registered', {
         hostInfo,
         name,
@@ -160,8 +187,8 @@ function createRegistryService(db, { bus, events }){
 
     const id = `res_${uuid()}`;
     db.prepare(
-      `INSERT INTO resources (id, name, type, status, labels, group_ids, host_info, token_hash, client_id, created_at)
-       VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`
+      `INSERT INTO resources (id, name, type, status, labels, group_ids, host_info, remote_addr, client_version, token_hash, client_id, created_at)
+       VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`
     ).run(
       id,
       name,
@@ -169,7 +196,9 @@ function createRegistryService(db, { bus, events }){
       RESOURCE_STATES.REGISTERED,
       JSON.stringify(labels),
       JSON.stringify(groups),
-      JSON.stringify(hostInfo || {}),
+      JSON.stringify(hostInfo),
+      remote,
+      clientVersion,
       hashToken(resourceToken),
       clientId,
       new Date().toISOString()
@@ -185,7 +214,7 @@ function createRegistryService(db, { bus, events }){
   }
 
   // Reconcile status from a heartbeat's self-reported state (§5.1).
-  function heartbeat(resourceId, { state, activeJobId, localLock, metrics } = {}){
+  function heartbeat(resourceId, { state, activeJobId, localLock, metrics, addresses, remoteAddr, clientVersion = null } = {}){
     const resource = get(resourceId);
     if (!resource){
       throw Object.assign(new Error('Unknown resource'), { status: 404 });
@@ -217,11 +246,26 @@ function createRegistryService(db, { bus, events }){
       busyReason = null;
     }
 
+    // Older Clients don't send addresses — keep whatever registration stored.
+    const cleanAddresses = sanitizeAddresses(addresses),
+      hostInfo = cleanAddresses ? { ...(resource.host_info || {}), addresses: cleanAddresses } : resource.host_info;
+
     db.prepare(
       `UPDATE resources
-       SET last_heartbeat_at = ?, status = ?, busy_source = ?, busy_reason = ?
+       SET last_heartbeat_at = ?, status = ?, busy_source = ?, busy_reason = ?, host_info = ?,
+           remote_addr = COALESCE(?, remote_addr), client_version = COALESCE(?, client_version)
        WHERE id = ?`
-    ).run(new Date().toISOString(), nextStatus, busySource, busyReason, resourceId);
+    ).run(
+      new Date().toISOString(),
+      nextStatus,
+      busySource,
+      busyReason,
+      hostInfo ? JSON.stringify(hostInfo) : null,
+      normalizeRemoteAddr(remoteAddr),
+      clientVersion,
+      resourceId
+    );
+    completeUpdateIfDone(resourceId);
 
     if (resource.status !== nextStatus){
       events.record('resource', resourceId, 'resource.status_changed', {
@@ -285,6 +329,40 @@ function createRegistryService(db, { bus, events }){
     bus.emit('resource.idle', { resourceId });
   }
 
+  // Self-update requests (README §10.2): delivered as a `self-update`
+  // command on every heartbeat until the Client reports `update_to` (or
+  // newer). `version` null cancels a pending one.
+  function setUpdateTo(resourceId, version){
+    if (!get(resourceId)){
+      throw Object.assign(new Error('Unknown resource'), { status: 404 });
+    }
+    db.prepare('UPDATE resources SET update_to = ? WHERE id = ?').run(version, resourceId);
+    events.record('resource', resourceId, version ? 'resource.update_requested' : 'resource.update_canceled', { version });
+  }
+
+  // Every resource not already on `version` or newer.
+  function requestUpdateAll(version){
+    const ids = list()
+      .filter((r) => !r.client_version || compareVersions(r.client_version, version) < 0)
+      .map((r) => r.id);
+    ids.forEach((id) => setUpdateTo(id, version));
+    return ids.length;
+  }
+
+  function completeUpdateIfDone(resourceId){
+    const r = get(resourceId);
+    if (r?.update_to && r.client_version && compareVersions(r.client_version, r.update_to) >= 0){
+      db.prepare('UPDATE resources SET update_to = NULL WHERE id = ?').run(resourceId);
+      events.record('resource', resourceId, 'resource.updated', { version: r.client_version });
+    }
+  }
+
+  // The version a heartbeating Client should update to, if any.
+  function pendingUpdate(resourceId){
+    const r = get(resourceId);
+    return r?.update_to && (!r.client_version || compareVersions(r.client_version, r.update_to) < 0) ? r.update_to : null;
+  }
+
   function setMaintenance(resourceId, enabled){
     const resource = get(resourceId);
     if (!resource){
@@ -338,6 +416,9 @@ function createRegistryService(db, { bus, events }){
     markOutOfService,
     markIdleAfterJob,
     setMaintenance,
+    setUpdateTo,
+    requestUpdateAll,
+    pendingUpdate,
     assignToJob,
     findIdleCandidates,
     everSatisfiable

package/src/services/updates.js

@@ -0,0 +1,83 @@
+/**
+ * @file        packages/coordinator/src/services/updates.js
+ * @description Periodic new-version check of the Coordinator, Agent and Client npm packages (README §10.2)
+ *
+ * @author      Andrian Yablonskyy
+ * @copyright   Copyright (c) 2026 Andrian Yablonskyy. All rights reserved.
+ *
+ * This file is part of TestHub and is proprietary and confidential.
+ * Unauthorized copying, modification, distribution, or use of this file,
+ * via any medium, is strictly prohibited without prior written permission
+ * from AdSystem.PRO.
+ */
+
+'use strict';
+
+const { PACKAGES, fetchLatestVersion, defaultRegistry, isNewer } = require('@andrian.yablonskyy/thub-common'),
+  { version: coordinatorVersion } = require('../../package.json');
+
+// Latest published versions, refreshed every `updates.checkIntervalHours`
+// and on demand from the dashboard. Kept in memory only — a restart just
+// checks again.
+function createUpdatesService({ config }){
+  const registry = config.updates.registry || defaultRegistry(),
+    state = { latest: {}, checkedAt: null, error: null };
+  let inFlight = null;
+
+  async function checkNow(){
+    // Concurrent callers (timer + a dashboard click) share one check.
+    inFlight = inFlight || (async () => {
+      const latest = {},
+        errors = [];
+      await Promise.all(Object.entries(PACKAGES).map(async ([app, pkg]) => {
+        try {
+          latest[app] = await fetchLatestVersion(pkg, { registry });
+        }
+        catch (err){
+          errors.push(err.message);
+        }
+      }));
+      state.latest = { ...state.latest, ...latest };
+      state.checkedAt = new Date().toISOString();
+      state.error = errors.length ? errors.join('; ') : null;
+      return status();
+    })().finally(() => {
+      inFlight = null;
+    });
+    return inFlight;
+  }
+
+  function status(){
+    return {
+      ...state,
+      coordinatorVersion,
+      coordinatorUpdate: isNewer(state.latest.coordinator, coordinatorVersion) ? state.latest.coordinator : null
+    };
+  }
+
+  // The version a self-update request targets: the latest known one,
+  // checking first if nothing has been fetched yet.
+  async function targetVersion(app){
+    if (!state.latest[app]){
+      await checkNow();
+    }
+    if (!state.latest[app]){
+      throw Object.assign(new Error(`Latest ${app} version unknown (${state.error || 'registry unreachable'})`), { status: 503 });
+    }
+    return state.latest[app];
+  }
+
+  function start(){
+    const hours = Number(config.updates.checkIntervalHours);
+    if (!(hours > 0)){
+      return;
+    }
+    checkNow().catch(() => {});
+    const timer = setInterval(() => checkNow().catch(() => {}), hours * 3600 * 1000);
+    timer.unref?.();
+  }
+
+  return { checkNow, status, targetVersion, start };
+}
+
+module.exports = { createUpdatesService };

package/src/web/routes.js

@@ -20,7 +20,7 @@ const fs = require('node:fs'),
   multer = require('multer'),
   { requireAdminSession, requireAdminRole } = require('../auth'),
   { attachJobStream } = require('../api/sse'),
-  { RESOURCE_STATES, JOB_STATES, ACTIVE_JOB_STATES } = require('@andrian.yablonskyy/thub-common');
+  { RESOURCE_STATES, JOB_STATES, ACTIVE_JOB_STATES, isNewer } = require('@andrian.yablonskyy/thub-common');
 
 // §10.1: avatar uploads are small, single images — a hard size cap and an
 // allow-list of image mimetypes, same spirit as the join-key/token checks
@@ -45,10 +45,21 @@ function createWebRouter({ services, config }){
     req.session.flash.push({ type, text });
   }
 
+  // Where a resource action (maintenance, rotate token) came from — the
+  // Resources page or the Overview's resource card. Only a local path,
+  // never another site.
+  function returnTo(req, fallback){
+    const target = req.body.returnTo;
+    return typeof target === 'string' && /^\/(?![\/\\])/.test(target) ? target : fallback;
+  }
+
   router.use((req, res, next) => {
     const user = req.session?.user || null;
     res.locals.user = user;
     res.locals.messages = req.session?.flash || [];
+    // Latest published versions (README §10.2) — navbar, Agents, Resources.
+    res.locals.updates = services.updates.status();
+    res.locals.isNewer = isNewer;
     if (req.session){
       req.session.flash = [];
     }
@@ -198,8 +209,9 @@ function createWebRouter({ services, config }){
       jobsLast24h = services.jobs
         .list({ limit: 1000 })
         .filter((j) => j.created_at >= dayAgo).length,
-      onlineCount = resources.filter((r) => r.status !== RESOURCE_STATES.OUT_OF_SERVICE && r.status !== RESOURCE_STATES.REGISTERED).length;
-    res.render('index', { title: 'Overview', active: 'overview', resources, queueLength, jobsLast24h, onlineCount });
+      onlineCount = resources.filter((r) => r.status !== RESOURCE_STATES.OUT_OF_SERVICE && r.status !== RESOURCE_STATES.REGISTERED).length,
+      groupsById = Object.fromEntries(services.groups.list().map((g) => [g.id, g]));
+    res.render('index', { title: 'Overview', active: 'overview', resources, queueLength, jobsLast24h, onlineCount, groupsById });
   });
 
   router.get('/resources', (req, res) => {
@@ -214,7 +226,7 @@ function createWebRouter({ services, config }){
 
   router.post('/resources/:id/maintenance', requireAdminRole, (req, res) => {
     services.registry.setMaintenance(req.params.id, req.body.enabled === '1');
-    res.redirect('/resources');
+    res.redirect(returnTo(req, '/resources'));
   });
 
   router.post('/resources/:id/rotate-token', requireAdminRole, (req, res) => {
@@ -223,9 +235,62 @@ function createWebRouter({ services, config }){
     services.db.prepare('UPDATE resources SET token_hash = ? WHERE id = ?').run(hashToken(token), req.params.id);
     services.events.record('resource', req.params.id, 'resource.token_rotated', {});
     flash(req, 'warning', `New resource token (copy it now): ${token}`);
-    res.redirect('/resources');
+    res.redirect(returnTo(req, '/resources'));
   });
 
+  // Self-update (README §10.2). Clients get a `self-update` heartbeat
+  // command, Agents update on their next run; both target the latest
+  // published version. The Coordinator itself is only ever updated by hand.
+  function updateAction(fn){
+    return async (req, res) => {
+      try {
+        flash(req, 'info', await fn(req));
+      }
+      catch (err){
+        flash(req, 'danger', err.message);
+      }
+      res.redirect(returnTo(req, '/'));
+    };
+  }
+
+  router.post('/updates/check', requireAdminRole, updateAction(async () => {
+    const s = await services.updates.checkNow(),
+      found = Object.entries(s.latest).map(([app, v]) => `${app} v${v}`).join(', ');
+    return s.error ? `Version check: ${found || 'nothing found'} (errors: ${s.error})` : `Latest versions: ${found}.`;
+  }));
+
+  router.post('/resources/update-all', requireAdminRole, updateAction(async () => {
+    const version = await services.updates.targetVersion('client'),
+      n = services.registry.requestUpdateAll(version);
+    return `Requested update to client v${version} on ${n} resource(s).`;
+  }));
+
+  router.post('/resources/:id/update', requireAdminRole, updateAction(async (req) => {
+    if (req.body.cancel === '1'){
+      services.registry.setUpdateTo(req.params.id, null);
+      return 'Update request canceled.';
+    }
+    const version = await services.updates.targetVersion('client');
+    services.registry.setUpdateTo(req.params.id, version);
+    return `Requested update to client v${version} — it starts on the Client's next heartbeat.`;
+  }));
+
+  router.post('/admin/agents/update-all', requireAdminRole, updateAction(async () => {
+    const version = await services.updates.targetVersion('agent'),
+      n = services.agents.requestUpdateAll(version);
+    return `Requested update to agent v${version} for ${n} agent(s) — each updates on its next run.`;
+  }));
+
+  router.post('/admin/agents/:id/update', requireAdminRole, updateAction(async (req) => {
+    if (req.body.cancel === '1'){
+      services.agents.setUpdateTo(req.params.id, null);
+      return 'Update request canceled.';
+    }
+    const version = await services.updates.targetVersion('agent');
+    services.agents.setUpdateTo(req.params.id, version);
+    return `Requested update to agent v${version} — it updates on its next run.`;
+  }));
+
   router.get('/jobs', (req, res) => {
     const filters = { state: req.query.state || undefined, source: req.query.source || undefined },
       jobs = services.jobs.list({ ...filters, limit: 200 }).map((j) => ({

package/views/admin/agents.pug

@@ -1,9 +1,12 @@
 extends ../layout
+include ../mixins/updates
 
 block content
   .d-flex.justify-content-between.align-items-center.mb-3
     h1.h4.mb-0 Agents (CI / developers)
     button.btn.btn-primary.btn-sm(type="button" data-bs-toggle="modal" data-bs-target="#addAgentModal") Register agent
+  .mb-3
+    +updatesToolbar('agent', 'agents', '/admin/agents')
 
   if newToken
     .alert.alert-warning
@@ -16,6 +19,7 @@ block content
       tr
         th Name
         th Kind
+        th Version
         th Created
         th Last used
         th Status
@@ -25,13 +29,16 @@ block content
         tr(class=a.revoked_at ? 'opacity-50' : '')
           td= a.name
           td.text-uppercase= a.kind
+          td: +versionCell(a.version, updates.latest.agent, a.update_to)
           td= fmtDate(a.created_at)
           td= fmtDate(a.last_used_at, 'never')
           td= a.revoked_at ? 'revoked' : 'active'
           td
             if !a.revoked_at
-              form(method="post" action=`/admin/agents/${a.id}/revoke` onsubmit="return confirm('Revoke this agent token?')")
-                button.btn.btn-sm.btn-outline-danger(type="submit") Revoke
+              .d-flex.justify-content-end
+                +updateButton(`/admin/agents/${a.id}/update`, a.update_to, '/admin/agents')
+                form.ms-1(method="post" action=`/admin/agents/${a.id}/revoke` onsubmit="return confirm('Revoke this agent token?')")
+                  button.btn.btn-sm.btn-outline-danger(type="submit") Revoke
 
   .modal(tabindex="-1" id="addAgentModal")
     .modal-dialog

package/views/index.pug

@@ -1,5 +1,7 @@
 extends layout
 include mixins/status-badge
+include mixins/resource
+include mixins/updates
 
 block content
   h1.h4.mb-2 Overview
@@ -24,7 +26,7 @@ block content
   .row.g-3
     each r in resources
       .col-sm-6.col-md-4.col-lg-3
-        .card.h-100(class=`border-${{IDLE:'success',BUSY:'primary',OUT_OF_SERVICE:'danger',MAINTENANCE:'secondary',REGISTERED:'secondary'}[r.status] || 'secondary'}`)
+        .card.h-100(role="button" tabindex="0" data-resource-card=`resource-card-${r.id}` class=`border-${{IDLE:'success',BUSY:'primary',OUT_OF_SERVICE:'danger',MAINTENANCE:'secondary',REGISTERED:'secondary'}[r.status] || 'secondary'}`)
           .card-body
             h5.card-title= r.name
             p.card-text.mb-1
@@ -35,3 +37,9 @@ block content
               p.card-text.small.text-body-secondary busy: #{r.busy_source} #{r.busy_reason ? '— ' + r.busy_reason : ''}
             p.card-text.small.text-body-secondary
               | heartbeat: #{fmtDate(r.last_heartbeat_at, 'never')}
+
+  each r in resources
+    +resourceCard(r, groupsById, '/')
+
+block scripts
+  script(src="/js/resource-card.js")

package/views/layout.pug

@@ -10,7 +10,16 @@ html(lang="en" data-bs-theme=(user && user.theme) || "auto")
   body
     nav.navbar.navbar-expand-lg.bg-body-tertiary.border-bottom
       .container-fluid
-        a.navbar-brand(href="/") TestHub
+        a.navbar-brand.d-flex.flex-column.lh-1.py-1(href="/")
+          span TestHub
+          small.text-body-secondary.fw-normal.mt-1(style="font-size: .7rem;")
+            | ver. #{coordinatorVersion}
+            if user && updates.coordinatorUpdate
+              span.badge.text-bg-warning.ms-1(
+                data-bs-toggle="tooltip"
+                data-bs-placement="bottom"
+                data-bs-title="Update the Coordinator by hand on its host: thub-admin self-update"
+              )= `v${updates.coordinatorUpdate} available`
         button.navbar-toggler(type="button" data-bs-toggle="collapse" data-bs-target="#nav")
           span.navbar-toggler-icon
         #nav.collapse.navbar-collapse

package/views/mixins/resource.pug

@@ -0,0 +1,93 @@
+//- Resource actions and the resource info card (modal), shared by the
+//- Overview and Resources pages. `returnTo` is the page the action forms
+//- redirect back to.
+
+mixin resourceActions(r, returnTo)
+  form.d-inline(method="post" action=`/resources/${r.id}/maintenance`)
+    input(type="hidden" name="enabled" value=r.status === 'MAINTENANCE' ? '0' : '1')
+    input(type="hidden" name="returnTo" value=returnTo)
+    if r.status === 'MAINTENANCE'
+      button.btn.btn-sm.btn-outline-secondary(
+        type="submit"
+        aria-label="Enable"
+        data-bs-toggle="tooltip"
+        data-bs-title="Bring this resource back into rotation so the scheduler can assign it jobs again"
+      )
+        i.bi.bi-play-circle
+    else
+      button.btn.btn-sm.btn-outline-secondary(
+        type="submit"
+        aria-label="Disable"
+        data-bs-toggle="tooltip"
+        data-bs-title="Take this resource out of rotation for maintenance — the scheduler will skip it"
+      )
+        i.bi.bi-tools
+  form.d-inline.ms-1(method="post" action=`/resources/${r.id}/rotate-token` onsubmit="return confirm('Rotate token? The Client will need the new one.')")
+    input(type="hidden" name="returnTo" value=returnTo)
+    button.btn.btn-sm.btn-outline-warning(
+      type="submit"
+      aria-label="Rotate token"
+      data-bs-toggle="tooltip"
+      data-bs-title="Invalidate the current resource token and issue a new one — the Client won't reconnect until it has it"
+    )
+      i.bi.bi-arrow-repeat
+  +updateButton(`/resources/${r.id}/update`, r.update_to, returnTo)
+
+mixin resourceCard(r, groupsById, returnTo)
+  - const isLoopback = (a) => /^127\./.test(a) || a === '::1' || a === 'localhost'
+  - const local = ((r.host_info && r.host_info.addresses) || []).filter((a) => !isLoopback(a.address))
+  - const external = r.remote_addr && !isLoopback(r.remote_addr) ? r.remote_addr : null
+  .modal.fade(id=`resource-card-${r.id}` tabindex="-1" aria-labelledby=`resource-card-${r.id}-title` aria-hidden="true")
+    .modal-dialog.modal-dialog-centered
+      .modal-content
+        .modal-header
+          h5.modal-title(id=`resource-card-${r.id}-title`)= r.name
+          button.btn-close(type="button" data-bs-dismiss="modal" aria-label="Close")
+        .modal-body
+          dl.row.mb-0
+            dt.col-sm-4 Name
+            dd.col-sm-8= r.name
+            dt.col-sm-4 Type
+            dd.col-sm-8.text-uppercase= r.type
+            dt.col-sm-4 Status
+            dd.col-sm-8: +resourceBadge(r.status)
+            dt.col-sm-4 Client version
+            dd.col-sm-8: +versionCell(r.client_version, updates.latest.client, r.update_to)
+            dt.col-sm-4 IP addresses
+            dd.col-sm-8
+              if !local.length && !external
+                span.text-body-secondary —
+              ul.list-unstyled.mb-0
+                each a in local
+                  li
+                    code= a.address
+                    span.text-body-secondary.small.ms-2= a.iface ? `${a.iface} · ${a.family}` : a.family
+                if external
+                  li
+                    code= external
+                    span.text-body-secondary.small.ms-2(
+                      data-bs-toggle="tooltip"
+                      data-bs-title="The address the Coordinator last saw this Client connect from"
+                    ) external
+            dt.col-sm-4 Labels
+            dd.col-sm-8
+              if r.labels.length
+                each l in r.labels
+                  span.badge.text-bg-light.border.me-1= l
+              else
+                span.text-body-secondary —
+            dt.col-sm-4 Groups
+            dd.col-sm-8
+              if r.group_ids.length
+                each gid in r.group_ids
+                  span.badge.text-bg-info.me-1(title=gid)= groupsById[gid] ? groupsById[gid].name : `(unknown: ${gid})`
+              else
+                span.text-body-secondary —
+            dt.col-sm-4 Busy source / reason
+            dd.col-sm-8= r.busy_source ? `${r.busy_source}${r.busy_reason ? ' — ' + r.busy_reason : ''}` : '—'
+            dt.col-sm-4 Last heartbeat
+            dd.col-sm-8= fmtDate(r.last_heartbeat_at, 'never')
+            if user.role === 'admin'
+              dt.col-sm-4 Actions
+              dd.col-sm-8.mb-0
+                +resourceActions(r, returnTo)

package/views/mixins/updates.pug

@@ -0,0 +1,67 @@
+//- Version display and self-update controls (README §10.2), shared by
+//- the Agents and Resources pages and the resource card.
+
+//- An app's reported version, plus a pending update request or a newer
+//- published version.
+mixin versionCell(current, latest, updateTo)
+  span= current ? `v${current}` : '—'
+  if updateTo
+    span.badge.text-bg-warning.ms-1(
+      data-bs-toggle="tooltip"
+      data-bs-title="Self-update requested — cleared once it reports this version"
+    )= `→ v${updateTo}`
+  else if current && isNewer(latest, current)
+    span.badge.text-bg-secondary.ms-1(
+      data-bs-toggle="tooltip"
+      data-bs-title=`v${latest} is available`
+    ) update available
+
+//- Latest published version of `app` (agent | client), "check now" and,
+//- for admins, "update all".
+mixin updatesToolbar(app, label, returnTo)
+  .d-flex.flex-wrap.align-items-center.gap-2.small.text-body-secondary
+    span
+      | Latest #{app}:
+      = ' '
+      strong= updates.latest[app] ? `v${updates.latest[app]}` : 'unknown'
+      if updates.checkedAt
+        = ` · checked ${fmtDate(updates.checkedAt)}`
+      if updates.error
+        i.bi.bi-exclamation-triangle.text-warning.ms-1(data-bs-toggle="tooltip" data-bs-title=updates.error)
+    if user.role === 'admin'
+      form.d-inline(method="post" action="/updates/check")
+        input(type="hidden" name="returnTo" value=returnTo)
+        button.btn.btn-sm.btn-outline-secondary(type="submit")
+          i.bi.bi-arrow-clockwise.me-1
+          | Check for updates
+      form.d-inline(
+        method="post"
+        action=app === 'agent' ? '/admin/agents/update-all' : '/resources/update-all'
+        onsubmit=`return confirm('Request a self-update of every ${label} to the latest version?')`
+      )
+        input(type="hidden" name="returnTo" value=returnTo)
+        button.btn.btn-sm.btn-outline-primary(type="submit" disabled=!updates.latest[app])
+          i.bi.bi-cloud-download.me-1
+          = `Update all ${label}`
+
+//- Per-item "Update" / "Cancel update" button.
+mixin updateButton(action, pending, returnTo)
+  form.d-inline.ms-1(method="post" action=action)
+    input(type="hidden" name="returnTo" value=returnTo)
+    if pending
+      input(type="hidden" name="cancel" value="1")
+      button.btn.btn-sm.btn-outline-warning(
+        type="submit"
+        aria-label="Cancel update"
+        data-bs-toggle="tooltip"
+        data-bs-title=`Cancel the pending self-update to v${pending}`
+      )
+        i.bi.bi-x-circle
+    else
+      button.btn.btn-sm.btn-outline-primary(
+        type="submit"
+        aria-label="Update"
+        data-bs-toggle="tooltip"
+        data-bs-title="Self-update to the latest published version"
+      )
+        i.bi.bi-cloud-download

package/views/resources/list.pug

@@ -1,16 +1,22 @@
 extends ../layout
 include ../mixins/status-badge
+include ../mixins/resource
+include ../mixins/updates
 
 block content
   h1.h4.mb-3 Resources
   p.text-body-secondary.small.
-    Resources register themselves — start a Client with the shared join key and it appears here.
+    Resources register themselves — start a Client with the shared join key and it appears here. Click a resource for its details, including IP addresses.
+
+  .mb-3
+    +updatesToolbar('client', 'clients', '/resources')
 
   table.table.table-hover.align-middle
     thead
       tr
         th Name
         th Type
+        th Version
         th Status
         th Labels
         th Groups
@@ -20,9 +26,10 @@ block content
           th Actions
     tbody
       each r in resources
-        tr
+        tr(role="button" tabindex="0" data-resource-card=`resource-card-${r.id}`)
           td= r.name
           td.text-uppercase= r.type
+          td: +versionCell(r.client_version, updates.latest.client, r.update_to)
           td: +resourceBadge(r.status)
           td
             each l in r.labels
@@ -37,29 +44,10 @@ block content
           td= fmtDate(r.last_heartbeat_at, 'never')
           if user.role === 'admin'
             td
-              form.d-inline(method="post" action=`/resources/${r.id}/maintenance`)
-                input(type="hidden" name="enabled" value=r.status === 'MAINTENANCE' ? '0' : '1')
-                if r.status === 'MAINTENANCE'
-                  button.btn.btn-sm.btn-outline-secondary(
-                    type="submit"
-                    aria-label="Enable"
-                    data-bs-toggle="tooltip"
-                    data-bs-title="Bring this resource back into rotation so the scheduler can assign it jobs again"
-                  )
-                    i.bi.bi-play-circle
-                else
-                  button.btn.btn-sm.btn-outline-secondary(
-                    type="submit"
-                    aria-label="Disable"
-                    data-bs-toggle="tooltip"
-                    data-bs-title="Take this resource out of rotation for maintenance — the scheduler will skip it"
-                  )
-                    i.bi.bi-tools
-              form.d-inline.ms-1(method="post" action=`/resources/${r.id}/rotate-token` onsubmit="return confirm('Rotate token? The Client will need the new one.')")
-                button.btn.btn-sm.btn-outline-warning(
-                  type="submit"
-                  aria-label="Rotate token"
-                  data-bs-toggle="tooltip"
-                  data-bs-title="Invalidate the current resource token and issue a new one — the Client won't reconnect until it has it"
-                )
-                  i.bi.bi-arrow-repeat
+              +resourceActions(r, '/resources')
+
+  each r in resources
+    +resourceCard(r, groupsById, '/resources')
+
+block scripts
+  script(src="/js/resource-card.js")