@andrian.yablonskyy/thub-coordinator 1.1.16 → 1.1.18

package/README.md

@@ -172,7 +172,7 @@ The Coordinator's own version (`ver. X.Y.Z`) is shown under the TestHub logo, to
 **Versions and self-update.** The Coordinator checks the npm registry for the latest Coordinator, Agent and Client every `updates.checkIntervalMin` (default 15 minutes, `0` disables; the older `checkIntervalHours` is ignored; `updates.registry` for a private mirror) and immediately with the navbar's **check for updates** button (admins; also on the Agents and Resources pages), which reports in a toast whether the Coordinator is current and which connected resources can update their Client. A newer Coordinator shows as an **Update app to X.Y.Z** button in the navbar for admins (a badge under the logo for viewers); 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, only when started with `--self-update` (off by default; under systemd add it to the unit's `ExecStart`, a re-install keeps it): the **Update app** button writes `<dataDir>/update-request.json`; the root `thub-coordinator-update.path` unit (installed by `sudo npm i -g`) runs `npm i -g` for it, and the postinstall restarts the service (the dashboard and API are briefly down). Logs: `journalctl -u thub-coordinator-update`. Without that unit, use `thub-admin self-update` on the host.
+- The Coordinator itself, only when started with `--self-update` (a systemd install has it; elsewhere, e.g. in a container, it's off and the dashboard shows nothing about Coordinator updates): the **Update app** button writes `<dataDir>/update-request.json`; the root `thub-coordinator-update.path` unit (installed by `sudo npm i -g`) runs `npm i -g` for it, and the postinstall restarts the service (the dashboard and API are briefly down). Logs: `journalctl -u thub-coordinator-update`. Without that unit, use `thub-admin self-update` on the host.
 
 A request is cleared when the Agent/Client reports the new version.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@andrian.yablonskyy/thub-coordinator",
-  "version": "1.1.16",
+  "version": "1.1.18",
   "description": "TestHub Coordinator — job queue, resource registry, scheduler, heartbeat monitor, log/artifact store and web dashboard",
   "main": "src/server.js",
   "engines": {
@@ -19,7 +19,7 @@
     "lint:fix": "eslint . --fix"
   },
   "dependencies": {
-    "@andrian.yablonskyy/thub-common": "^1.1.4",
+    "@andrian.yablonskyy/thub-common": "^1.1.5",
     "better-sqlite3": "^12.4.1",
     "express": "^5.1.0",
     "express-session": "^1.18.2",

package/public/js/client-config.js

@@ -40,9 +40,18 @@
     });
   }
 
-  // An HW Client's hw-devices section (the only Clients with a form).
+  // An HW Client's hw-devices section (the only Clients with a form), with
+  // what its tabs don't edit (data-keep: usbPower) as it was loaded.
   function sectionFrom(form){
+    let keep = {};
+    try {
+      keep = JSON.parse(form.dataset.keep || '{}');
+    }
+    catch {
+      keep = {};
+    }
     return {
+      ...keep,
       stlinks: rows(form, 'stlinks'),
       uarts: rows(form, 'uarts'),
       usbs: rows(form, 'usbs')

package/scripts/install-systemd-unit.js

@@ -34,23 +34,15 @@ const fs = require('node:fs'),
 // The checked-in unit only has placeholders — fill in the target user and
 // wherever *this* install's node and server.js actually are, so it works
 // regardless of npm prefix or an nvm-managed Node.
-// `--self-update` (README §10.2) is off by default; once added to the
-// installed unit's ExecStart, a re-install keeps it there.
-function selfUpdateFlag(existingUnit = UNIT_DEST){
-  try {
-    return /^ExecStart=.*\s--self-update(\s|$)/m.test(fs.readFileSync(existingUnit, 'utf8')) ? ' --self-update' : '';
-  }
-  catch {
-    return '';
-  }
-}
-
 function renderUnit(user, paths){
   return fs.readFileSync(UNIT_SRC, 'utf8')
     .replace(/^User=.*$/m, `User=${user.name}`)
     .replace(/^Group=.*$/m, `Group=${user.gid}`)
     .replace(/^Environment=THUB_COORDINATOR_CONFIG=.*$/m, `Environment=THUB_COORDINATOR_CONFIG=${paths.configPath}`)
-    .replace(/^ExecStart=.*$/m, `ExecStart=${process.execPath} ${SERVER_PATH}${selfUpdateFlag()}`)
+    // --self-update: the dashboard's "Update app" (README §10.2), through the
+    // root thub-coordinator-update units installed below — on for a systemd
+    // install. To turn it off, override ExecStart in a drop-in.
+    .replace(/^ExecStart=.*$/m, `ExecStart=${process.execPath} ${SERVER_PATH} --self-update`)
     .replace(/^ReadWritePaths=.*$/m, `ReadWritePaths=${[paths.dataDir, paths.dbDir].filter(Boolean).join(' ')}`);
 }
 

package/src/api/agent.js

@@ -1,6 +1,6 @@
 /**
  * @file        packages/coordinator/src/api/agent.js
- * @description Agent API routes: job submission, status, cancel, log streaming (README §6.1)
+ * @description Agent API routes: job submission, status, cancel, USB power, log streaming (README §6.1)
  *
  * @author      Andrian Yablonskyy
  * @copyright   Copyright (c) 2026 Andrian Yablonskyy. All rights reserved.
@@ -88,6 +88,20 @@ function createAgentRouter({ services, config }){
     }
   });
 
+  // `thub power on|off|reset <jobId>` (README §8.7): the job's owner
+  // switches the USB power of the Client running it.
+  router.post('/jobs/:id/power', auth, visibleJob, (req, res, next) => {
+    try {
+      const { action, delaySec, port } = req.body || {};
+      res.status(202).json(services.jobs.requestPower(req.params.id, {
+        agentId: req.agent.id, action, delaySec, port, by: req.user?.username || req.agent.name
+      }));
+    }
+    catch (err){
+      next(err);
+    }
+  });
+
   router.get('/jobs/:id/logs', auth, visibleJob, (req, res) => {
     const after = Number(req.query.after || 0),
       limit = req.query.limit ? Number(req.query.limit) : undefined;

package/src/api/resource.js

@@ -148,6 +148,46 @@ function createResourceRouter({ services, config }){
     }
   });
 
+  // While a job runs, the Client long-polls here for commands (README §8.7),
+  // so its owner's power reset — or a cancel — doesn't wait for the next
+  // heartbeat. Answers as soon as there's one (heartbeats still drain
+  // them too: whichever asks first gets them), else after `wait` seconds.
+  router.get('/resources/:id/commands', auth, requireOwnResource, (req, res) => {
+    const waitSec = Math.min(Math.max(Number(req.query.wait) || 0, 0), 60),
+      id = req.params.id,
+      queued = services.commands.drain(id);
+    if (queued.length || waitSec === 0){
+      return res.json({ commands: queued });
+    }
+    let timer = null;
+    const done = () => {
+        clearTimeout(timer);
+        services.bus.off('command', onCommand);
+        res.off('close', onClose);
+      },
+      // After the commands service queued it (setImmediate): taken off the
+      // queue only if the Client is still there to get it.
+      onCommand = (evt) => {
+        if (evt.resourceId === id){
+          setImmediate(() => {
+            if (res.writableEnded || res.destroyed){
+              return;
+            }
+            done();
+            res.json({ commands: services.commands.drain(id) });
+          });
+        }
+      },
+      onClose = () => done();
+    timer = setTimeout(() => {
+      done();
+      res.json({ commands: [] });
+    }, waitSec * 1000);
+    services.bus.on('command', onCommand);
+    // The Client gave up (or shut down): stop waiting.
+    res.on('close', onClose);
+  });
+
   router.post('/resources/:id/status', auth, requireOwnResource, (req, res, next) => {
     try {
       const { busy, source, reason } = req.body;

package/src/services/jobs.js

@@ -13,7 +13,9 @@
 
 'use strict';
 
-const { validateJobSpec, maskEnv, JOB_STATES, ACTIVE_JOB_STATES, TERMINAL_JOB_STATES, RESOURCE_STATES } = require('@andrian.yablonskyy/thub-common'),
+const {
+    validateJobSpec, maskEnv, powerRequestErrors, DEFAULT_RESET_DELAY_SEC, JOB_STATES, ACTIVE_JOB_STATES, TERMINAL_JOB_STATES, RESOURCE_STATES
+  } = require('@andrian.yablonskyy/thub-common'),
   { LABEL_RE, LABEL_RULE } = require('./registry'),
   { paginate } = require('./list-prefs'),
   { parseTerms, likeClause } = require('./search'),
@@ -326,6 +328,46 @@ function createJobsService(db, { bus, events, registry, config }){
     return setState(id, JOB_STATES.CANCELED, reason ? { message: reason } : {});
   }
 
+  // Agent: POST /jobs/:id/power (`thub power`, README §8.7) — switch the USB
+  // power of the Client running the job, now. The job's owner only (not
+  // even an admin: it's their bench for as long as the job runs), and only
+  // while a Client has it. Delivered right away to a Client long-polling
+  // for commands, else with its next heartbeat; the Client logs it in the job.
+  function requestPower(id, { agentId, action, delaySec, port, by }){
+    const job = get(id);
+    if (!job){
+      throw Object.assign(new Error('Unknown job'), { status: 404 });
+    }
+    if (job.agent_id !== agentId){
+      throw Object.assign(new Error('Only the job\'s owner can switch its Client\'s USB power'), { status: 403 });
+    }
+    const errors = powerRequestErrors({ action, delaySec, port });
+    if (errors.length){
+      throw Object.assign(new Error(errors.join('; ')), { status: 400 });
+    }
+    // Not ASSIGNED: the Client may not have picked it up yet, and would
+    // drop a command for a job it doesn't know.
+    if (![JOB_STATES.PREPARING, JOB_STATES.RUNNING].includes(job.state) || !job.resource_id){
+      throw Object.assign(new Error(`Job ${id} is ${job.state} — USB power can only be switched while a Client is running it`), { status: 409 });
+    }
+    const r = registry.get(job.resource_id),
+      usbPower = r?.capabilities?.hw?.usbPower;
+    if (!usbPower?.ports?.length){
+      throw Object.assign(new Error(`${r?.name || 'The Client'} has no USB power ports (hw-devices.usbPower in its config), ` +
+        'or its thub-client is older than USB power'), { status: 409 });
+    }
+    if (!usbPower.available){
+      throw Object.assign(new Error(`${r.name} can't switch USB power: ${usbPower.reason || 'uhubctl is unavailable'}`), { status: 409 });
+    }
+    if (port && port > usbPower.ports.length){
+      throw Object.assign(new Error(`port ${port}: ${r.name} has ${usbPower.ports.length} USB power port(s)`), { status: 400 });
+    }
+    const request = { action, ...(action === 'reset' ? { delaySec: delaySec ?? DEFAULT_RESET_DELAY_SEC } : {}), ...(port ? { port } : {}) };
+    bus.emit('command', { resourceId: r.id, command: 'power', jobId: id, ...request, by });
+    events.record('job', id, 'job.power_requested', { ...request, by });
+    return { jobId: id, resource: { id: r.id, name: r.name }, ...request };
+  }
+
   // Admin "Reboot" on a Client (resource card): its running job is canceled
   // first (the host is going down anyway), then a `reboot` command goes out
   // with its next heartbeat — the Client reboots the host through its root
@@ -589,6 +631,7 @@ function createJobsService(db, { bus, events, registry, config }){
     setState,
     cancel,
     cancelPinnedTo,
+    requestPower,
     requestReboot,
     removeResource,
     completeRemoval,

package/src/services/registry.js

@@ -139,13 +139,27 @@ function sanitizeTypedCapabilities(caps){
       hw: {
         stlinks: capList(hw.stlinks).map(device),
         uarts: capList(hw.uarts).map(device),
-        usbs: capList(hw.usbs).map(device)
+        usbs: capList(hw.usbs).map(device),
+        usbPower: usbPowerCapability(hw.usbPower)
       }
     };
   }
   return null;
 }
 
+// The Client's uhubctl ports (README §8.7) and whether uhubctl is installed
+// there: null when it has none (or is older than USB power).
+function usbPowerCapability(p){
+  if (!p || typeof p !== 'object'){
+    return null;
+  }
+  return {
+    ports: capList(p.ports).map((x) => ({ hub: str(x?.hub, 64), port: num(x?.port) })),
+    available: p.available === true,
+    ...(p.available === true ? { version: str(p.version, 64) } : { reason: str(p.reason, 300) })
+  };
+}
+
 // Heartbeat durations (README §10) arrive as seconds relative to "now" on
 // the Client and are anchored to the Coordinator's clock here. Anything
 // negative, non-numeric or over ~10 years is ignored.

package/src/web/routes.js

@@ -807,9 +807,13 @@ function createWebRouter({ services, config }){
       return { type: 'danger', text: `Update check failed — the npm registry couldn't be reached (${s.error}). Nothing was checked.` };
     }
 
-    parts.push(s.coordinatorUpdate
-      ? `Coordinator v${s.coordinatorVersion} → v${s.coordinatorUpdate} available.`
-      : `Coordinator is up to date (v${s.coordinatorVersion}).`);
+    // The Coordinator's own version only when it can update itself
+    // (--self-update); Agents and Clients are always reported.
+    if (s.selfUpdate){
+      parts.push(s.coordinatorUpdate
+        ? `Coordinator v${s.coordinatorVersion} → v${s.coordinatorUpdate} available.`
+        : `Coordinator is up to date (v${s.coordinatorVersion}).`);
+    }
 
     const connected = services.registry.list().filter((r) => r.status !== RESOURCE_STATES.OUT_OF_SERVICE && r.last_heartbeat_at),
       outdated = connected.filter((r) => r.client_version && isNewer(s.latest.client, r.client_version)),
@@ -834,7 +838,7 @@ function createWebRouter({ services, config }){
     if (s.error){
       parts.push(`Some checks failed: ${s.error}`);
     }
-    const behind = s.coordinatorUpdate || outdated.length || unknown.length;
+    const behind = (s.selfUpdate && s.coordinatorUpdate) || outdated.length || unknown.length;
     return { type: behind || s.error ? 'warning' : 'success', text: parts.join('\n') };
   }));
 

package/systemd/thub-coordinator.service

@@ -3,8 +3,10 @@ Description=TestHub Coordinator
 After=network-online.target
 Wants=network-online.target
 
-# Add --self-update to ExecStart to let admins update the Coordinator from
-# the dashboard ("Update app", README §10.2); a re-install keeps it.
+# --self-update lets admins update the Coordinator from the dashboard
+# ("Update app", README §10.2) through thub-coordinator-update.path. To turn
+# it off: sudo systemctl edit thub-coordinator, then [Service], ExecStart=
+# (empty) and ExecStart=<the same line without --self-update>.
 # User, Group, THUB_COORDINATOR_CONFIG, ReadWritePaths and ExecStart are
 # rewritten by scripts/install-systemd-unit.js at install time to the user
 # who ran `sudo npm i -g` and this install's real node/server.js paths.
@@ -13,7 +15,7 @@ Type=simple
 User=thub
 Group=thub
 Environment=THUB_COORDINATOR_CONFIG=/var/lib/thub/.config/thub/coordinator.json
-ExecStart=/usr/bin/node /usr/lib/node_modules/@andrian.yablonskyy/thub-coordinator/src/server.js
+ExecStart=/usr/bin/node /usr/lib/node_modules/@andrian.yablonskyy/thub-coordinator/src/server.js --self-update
 Restart=always
 RestartSec=2
 NoNewPrivileges=yes

package/test/scheduler.test.js

@@ -726,13 +726,13 @@ test('config export/import: exported from the reported file (+ what\'s pending);
   assert.deepEqual(registry.exportClientConfig(sw), { name: 'sw1', type: 'sw', labels: ['x'] });
 });
 
-test('HW capabilities: no power control — reported relays/power dropped, and refused on Save', () => {
+test('HW capabilities: no older power control — reported relays/power dropped, and refused on Save', () => {
   const { registry } = buildTestServices(),
     { resourceId } = registry.registerAuto({
       clientId: 'c-hw', name: 'hw1', type: 'hw', labels: [],
       capabilities: { hw: { stlinks: [], uarts: [], usbs: [], relays: [{ channel: 0 }], power: { method: 'uhubctl', hub: '1-1', port: 2 } } }
     });
-  assert.deepEqual(registry.get(resourceId).capabilities.hw, { stlinks: [], uarts: [], usbs: [] });
+  assert.deepEqual(registry.get(resourceId).capabilities.hw, { stlinks: [], uarts: [], usbs: [], usbPower: null }); // usbPower: none configured
   assert.throws(() => registry.setClientConfig(resourceId, { relays: [{ channel: 0 }] }), /must NOT have additional properties/);
   assert.throws(() => registry.setClientConfig(resourceId, { power: null }), /must NOT have additional properties/);
 });

package/test/updates.test.js

@@ -105,9 +105,11 @@ test('on startup, a finished update\'s status is cleared; a failure is kept for
   assert.equal(fs.existsSync(statusFile), true);
 });
 
-test('self-update is off unless the Coordinator was started with --self-update: no request, no button', async (t) => {
+test('without --self-update: no request, no Coordinator check or button; Agents and Clients keep theirs', async (t) => {
   const dataDir = fs.mkdtempSync(path.join(os.tmpdir(), 'thub-updates-')),
-    updates = createUpdatesService({ config: { dataDir, updates: {} }, pathUnit: path.join(dataDir, 'fake.path'), fetchLatest: async () => '99.0.0' });
+    updates = createUpdatesService({
+      config: { dataDir, updates: {} }, pathUnit: path.join(dataDir, 'fake.path'), fetchLatest: async () => '99.0.0'
+    });
   fs.writeFileSync(path.join(dataDir, 'fake.path'), '');
   await updates.checkNow();
   assert.equal(updates.status().selfUpdate, false);
@@ -123,7 +125,9 @@ test('self-update is off unless the Coordinator was started with --self-update:
   for (const selfUpdate of [false, true]){
     const config = { ...loadConfig(file), selfUpdate },
       services = buildServices(config);
-    services.updates.checkNow = async () => {};
+    services.updates.checkNow = async () => ({
+      fetched: ['coordinator', 'client'], latest: { client: '9.9.9' }, coordinatorVersion: '1.0.0', coordinatorUpdate: '99.0.0', selfUpdate
+    });
     Object.assign(services.updates, { status: () => ({ latest: {}, coordinatorVersion: '1.0.0', coordinatorUpdate: '99.0.0', selfUpdate }) });
     services.adminUsers.create({ username: `root${selfUpdate}`, email: `r${selfUpdate}@example.com`, role: 'admin', password: 'pw' }, { by: 't' });
     const server = createApp(config, services).listen(0, '127.0.0.1');
@@ -137,7 +141,19 @@ test('self-update is off unless the Coordinator was started with --self-update:
         method: 'POST', body: new URLSearchParams({ username: `root${selfUpdate}`, password: 'pw' }), redirect: 'manual'
       })).headers.get('set-cookie').split(';')[0],
       html = await (await fetch(`${base}/runners`, { headers: { cookie } })).text();
+    // The Coordinator's own: Update app and the navbar's check — only with --self-update.
     assert.equal(/action="\/updates\/coordinator"/.test(html), selfUpdate, `Update app button with selfUpdate=${selfUpdate}`);
-    assert.match(html, /v99\.0\.0 available|Update app to 99\.0\.0/);
+    assert.equal(/action="\/updates\/check" data-submit-busy/.test(html), selfUpdate, `navbar update check with selfUpdate=${selfUpdate}`);
+    assert.equal(/99\.0\.0/.test(html.slice(0, html.indexOf('<main'))), selfUpdate); // nothing about a new Coordinator in the navbar
+    // Clients' (and Agents') check and update-all: always.
+    assert.match(html, /<form class="d-inline" method="post" action="\/updates\/check">/);
+    assert.match(html, /action="\/runners\/update-all"/);
+    // "Check for updates" (Runners page): Clients always, the Coordinator only with --self-update.
+    const check = await fetch(`${base}/updates/check`, {
+        method: 'POST', headers: { cookie }, body: new URLSearchParams({ returnTo: '/runners' }), redirect: 'manual'
+      }),
+      toast = await (await fetch(`${base}${check.headers.get('location')}`, { headers: { cookie } })).text();
+    assert.match(toast, /No connected runners|connected runner/);
+    assert.equal(/Coordinator v1\.0\.0 → v99\.0\.0 available/.test(toast), selfUpdate);
   }
 });

package/test/usb-power.test.js

@@ -0,0 +1,129 @@
+/**
+ * @file        packages/coordinator/test/usb-power.test.js
+ * @description Tests: `thub power` — the job owner switches its Client's USB power; the command reaches a Client
+ *              long-polling for commands at once
+ *
+ * @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 test = require('node:test'),
+  assert = require('node:assert/strict'),
+  fs = require('node:fs'),
+  os = require('node:os'),
+  path = require('node:path'),
+  { loadConfig } = require('../src/config'),
+  { buildServices, createApp } = require('../src/server');
+
+const USB_POWER = { ports: [{ hub: '1-1.4', port: 2 }, { hub: '1-1.4', port: 3 }], available: true, version: '2.6.0' };
+
+async function start(t){
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'thub-power-')),
+    file = path.join(dir, 'coordinator.json');
+  fs.writeFileSync(file, JSON.stringify({ dataDir: path.join(dir, 'data'), updates: { checkIntervalMin: 0 } }));
+  const config = loadConfig(file),
+    services = buildServices(config),
+    server = createApp(config, services).listen(0, '127.0.0.1');
+  t.after(() => new Promise((r) => {
+    server.closeAllConnections?.();
+    server.close(r);
+  }));
+  await new Promise((r) => server.on('listening', r));
+  const base = `http://127.0.0.1:${server.address().port}/api/v1`,
+    call = async (token, method, url, body) => {
+      const res = await fetch(`${base}${url}`, {
+        method,
+        headers: { authorization: `Bearer ${token}`, ...(body ? { 'content-type': 'application/json' } : {}) },
+        body: body ? JSON.stringify(body) : undefined
+      });
+      return { status: res.status, body: res.headers.get('content-type')?.includes('json') ? await res.json() : await res.text() };
+    };
+  return { services, call };
+}
+
+// A Client with `usbPower` capabilities (a job is only accepted when one
+// could run it), and then running job `jobId` (PREPARING).
+function client(services, { name, usbPower }){
+  return services.registry.registerAuto({ clientId: `id-${name}`, name, type: 'hw', labels: [], capabilities: { hw: { usbPower } } });
+}
+
+function runOn(services, { resourceId }, jobId){
+  services.registry.heartbeat(resourceId, { state: 'idle' });
+  services.scheduler.runPass();
+  assert.equal(services.jobs.get(jobId).resource_id, resourceId);
+  services.jobs.setState(jobId, 'PREPARING');
+}
+
+test('power: only the job\'s owner, only while a Client runs it; the Client gets it as a command', async (t) => {
+  const { services, call } = await start(t),
+    alice = services.agents.create({ name: 'alice', kind: 'cli' }).token,
+    ci = services.agents.create({ name: 'pipeline', kind: 'ci' }).token,
+    { resourceId, resourceToken } = client(services, { name: 'lab-hw-01', usbPower: USB_POWER }),
+    jobId = (await call(alice, 'POST', '/jobs', { target: { type: 'hw', client: 'lab-hw-01' }, command: './t.sh' })).body.jobId;
+
+  // Queued: no Client to switch yet.
+  assert.match((await call(alice, 'POST', `/jobs/${jobId}/power`, { action: 'reset' })).body.error,
+    /QUEUED — USB power can only be switched while a Client is running it/);
+
+  runOn(services, { resourceId }, jobId);
+
+  // A CI token sees the job, but it isn't its owner.
+  assert.equal((await call(ci, 'POST', `/jobs/${jobId}/power`, { action: 'reset' })).status, 403);
+  // Bad requests.
+  assert.match((await call(alice, 'POST', `/jobs/${jobId}/power`, { action: 'cycle' })).body.error, /action must be one of on, off, reset/);
+  assert.match((await call(alice, 'POST', `/jobs/${jobId}/power`, { action: 'off', delaySec: 2 })).body.error, /reset only/);
+  assert.match((await call(alice, 'POST', `/jobs/${jobId}/power`, { action: 'on', port: 3 })).body.error, /port 3: lab-hw-01 has 2 USB power port/);
+  services.commands.drain(resourceId); // the assignment's own, if any
+
+  const ok = await call(alice, 'POST', `/jobs/${jobId}/power`, { action: 'reset' });
+  assert.equal(ok.status, 202);
+  assert.deepEqual(ok.body, { jobId, resource: { id: resourceId, name: 'lab-hw-01' }, action: 'reset', delaySec: 1 }); // 1 s by default
+  const { body } = await call(resourceToken, 'GET', `/resources/${resourceId}/commands?wait=0`);
+  assert.deepEqual(body.commands, [{ command: 'power', jobId, action: 'reset', delaySec: 1, by: 'alice' }]);
+
+  // Not any more once it's over.
+  services.jobs.cancel(jobId, { agentId: null, isAdmin: true });
+  assert.equal((await call(alice, 'POST', `/jobs/${jobId}/power`, { action: 'on' })).status, 409);
+});
+
+test('power: refused for a Client without USB power ports, or without uhubctl', async (t) => {
+  const { services, call } = await start(t),
+    alice = services.agents.create({ name: 'alice', kind: 'cli' }).token,
+    old = client(services, { name: 'old-client' }),
+    noUhubctl = client(services, { name: 'no-uhubctl', usbPower: { ports: USB_POWER.ports, available: false, reason: 'uhubctl isn\'t installed' } }),
+    submit = async (on) => (await call(alice, 'POST', '/jobs', { target: { type: 'hw', client: on }, command: './t.sh' })).body.jobId,
+    first = await submit('old-client');
+  runOn(services, old, first);
+  assert.match((await call(alice, 'POST', `/jobs/${first}/power`, { action: 'on' })).body.error, /old-client has no USB power ports/);
+  services.jobs.cancel(first, { isAdmin: true });
+
+  const second = await submit('no-uhubctl');
+  runOn(services, noUhubctl, second);
+  assert.match((await call(alice, 'POST', `/jobs/${second}/power`, { action: 'on' })).body.error, /no-uhubctl can't switch USB power: uhubctl isn't installed/);
+});
+
+test('commands long-poll: answers as soon as a command is queued, else empty after `wait`', async (t) => {
+  const { services, call } = await start(t),
+    { resourceId, resourceToken } = services.registry.registerAuto({ clientId: 'c1', name: 'lab-hw-01', type: 'hw', labels: [] }),
+    listeners = services.bus.listenerCount('command'),
+    started = Date.now(),
+    polling = call(resourceToken, 'GET', `/resources/${resourceId}/commands?wait=10`);
+  await new Promise((r) => setTimeout(r, 100));
+  services.commands.push(resourceId, { command: 'cancel-job', jobId: 'M-00001' });
+  const { status, body } = await polling;
+  assert.equal(status, 200);
+  assert.deepEqual(body.commands, [{ command: 'cancel-job', jobId: 'M-00001' }]);
+  assert.ok(Date.now() - started < 2000);
+  assert.deepEqual(services.commands.drain(resourceId), []); // delivered once
+
+  assert.deepEqual((await call(resourceToken, 'GET', `/resources/${resourceId}/commands?wait=1`)).body, { commands: [] });
+  assert.equal(services.bus.listenerCount('command'), listeners); // none left behind
+  assert.equal((await call(resourceToken, 'GET', '/resources/someone-else/commands')).status, 403);
+});

package/test/views.test.js

@@ -53,7 +53,7 @@ test('help page renders every section with this Coordinator\'s URL', () => {
     coordinatorUrl: 'https://thub.example.test'
   });
   for (const id of ['overview', 'use-cases', 'quick-start', 'coordinator', 'agent-setup', 'client-setup',
-    'client-machines', 'docker', 'git', 'agent-cli', 'env', 'ci', 'troubleshooting']){
+    'client-machines', 'usb-power', 'lab-devices', 'docker', 'git', 'agent-cli', 'env', 'storage', 'ci', 'troubleshooting']){
     assert.match(html, new RegExp(`<section[^>]* id="${id}"`), `section #${id}`);
     assert.match(html, new RegExp(`href="#${id}"`), `TOC entry for #${id}`);
   }
@@ -62,6 +62,30 @@ test('help page renders every section with this Coordinator\'s URL', () => {
   // Troubleshooting: commands and parameters are <code>, placeholders escaped.
   assert.match(html, /<code>journalctl -u thub-client@&lt;instance&gt; -f<\/code>/);
   assert.match(html, /<span>The job is rejected with <code>422<\/code><\/span>/);
+  // USB port power (uhubctl): its setup, the Agent options and the FAQ.
+  assert.match(html, /sudo uhubctl -l 1-1\.4 -p 2 -a off/);
+  assert.match(html, /thub power off M-00131 && thub power on M-00131/);
+  assert.match(html, /<code class="text-nowrap">--power-on-start &lt;action&gt;<\/code>/);
+  assert.match(html, /<span>USB power: <code>No compatible devices detected!<\/code><\/span>/);
+  // Smart sockets and PDUs: driven by the job's own command or script.
+  assert.match(html, /curl -fsS --digest -u "admin:\$SHELLY_PASSWORD" "\$S&on=false"/);
+  assert.match(html, /# ci\/power.sh on\|off\|reset \[off-seconds\]/);
+  assert.match(html, /older AP79xx: sPDUOutletCtl …1\.4\.4\.2\.1\.3\.&lt;outlet&gt;\)/);
+  assert.match(html, /cd src &amp;&amp; exec ci\/run.sh|cd src && exec ci\/run.sh/);
+  // CI/CD for GitHub, GitLab, Bitbucket and Jenkins, all pointed at this Coordinator; artifact storage.
+  for (const file of ['.github/workflows/firmware.yml', '.gitlab-ci.yml', 'bitbucket-pipelines.yml', 'Jenkinsfile']){
+    assert.match(html, new RegExp(`<figcaption class="thub-code-caption">${file.replace(/\./g, '\\.')}</figcaption>`), file);
+  }
+  assert.match(html, /THUB_URL {12}= 'https:\/\/thub\.example\.test'/);
+  assert.match(html, /aws s3 presign "s3:\/\/fw-builds\/app\/\$SHA\/app\.bin" --expires-in 3600/);
+  assert.match(html, /size=\$\(wc -c &lt; "\$file"/); // < escaped in code blocks
+  // Certificates, SSH host-key pinning, per-registry docker login, Artifactory service auth.
+  assert.match(html, /Environment=NODE_EXTRA_CA_CERTS=\/usr\/local\/share\/ca-certificates\/lab-ca\.crt/);
+  assert.match(html, /curl -fsSL --cert "\$THUB_WORK_DIR\/c\.pem" --key "\$THUB_WORK_DIR\/k\.pem"/);
+  assert.match(html, /StrictHostKeyChecking=yes/);
+  assert.match(html, /<td><code>oauth2accesstoken<\/code><\/td>/);
+  assert.match(html, /-d scope=applied-permissions\/user -d expires_in=3600/);
+  assert.match(html, /<span>`?Download failed … \(SELF_SIGNED_CERT_IN_CHAIN\)|<span><code>Download failed … \(SELF_SIGNED_CERT_IN_CHAIN\)<\/code>/);
   // Code placeholders are escaped, never parsed as tags.
   assert.doesNotMatch(html, /<(url|jobId|groupId|resourceId|work|ref)>/);
 });

package/views/help/_agent-cli.pug

@@ -4,6 +4,7 @@
     thub run      [options]                 Submit a job and follow its log
     thub status   <jobId> [--json]          Status; follow the log if running, verdict and test counts if done
     thub cancel   <jobId>                   Cancel a job
+    thub power    on|off|reset <jobId> [--delay <sec>] [--port <n>]   Switch the USB power of the Client running your job
     thub resources [--json]                 Clients and their status
     thub jobs     [--mine] [--state <s>] [--json]   Recent jobs (a cli token: only its own)
     thub config   set <url|key|group|user> <value>
@@ -35,6 +36,11 @@
         ['--meta <key=value>', 'Metadata stored on the job (repeatable). The command sees THUB_META_<KEY>.', '--meta ciJobId=$GITHUB_RUN_ID'],
         ['--dry-run', 'Schedule for real, but only log what the Client would run.', '--dry-run']
       ] },
+      { title: 'USB power (HW, see USB port power)', rows: [
+        ['--power-on-start <action>', 'on, off or reset the Client\'s USB power ports before the command runs. A failure ends the job ERROR.', '--power-on-start reset'],
+        ['--power-on-end <action>', 'on, off or reset them when the job ends, whatever its verdict.', '--power-on-end off'],
+        ['--power-reset-delay <sec>', 'How long a reset keeps the power off: 0–60 s, default 1.', '--power-reset-delay 2']
+      ] },
       { title: 'Agent behavior', rows: [
         ['--wait', 'Follow to the end and exit with the verdict code (CI). Ctrl-C/SIGINT cancels the job.', '--wait'],
         ['--detach', 'Print the job id and exit.', '--detach --json'],
@@ -93,6 +99,13 @@
     JOB=$(thub run --type sw --command ./ci/test.sh --detach --json | jq -r .jobId)
     while thub status "$JOB" --json > job.json; [ $? -eq 5 ]; do sleep 10; done
     jq -r '"\(.state) exit=\(.exit_code) tests=\(.summary.total // 0) failed=\(.summary.failed // 0)"' job.json
+  +code('Power-cycle the board at the start; your job hung? reset it without canceling').
+    thub run --type hw --label board:nucleo-f401re --command ./ci/test.sh \
+      --power-on-start reset --power-reset-delay 2 --power-on-end off --detach
+    thub power reset M-00131 --delay 3          # owner only, while it runs
+  +code('Power-cycle a board on a smart socket from the test repository (see Smart sockets, PDUs, devices)').
+    thub run --type hw --label board:nucleo-f401re --env GH_TOKEN --env POWER_PASSWORD \
+      --command 'git clone --depth 1 "https://x-access-token:$GH_TOKEN@$TESTS_REPO" src && cd src && exec ci/run.sh' --wait
   +code('Lists').
     thub resources
     thub jobs --mine --state FAILED