@andrian.yablonskyy/thub-coordinator 1.0.16 → 1.0.17

package/package.json

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

package/src/services/jobs.js

@@ -91,11 +91,22 @@ function createJobsService(db, { bus, events, registry, artifacts, config }){
     }
     spec.source = source;
 
-    if (!registry.everSatisfiable(spec.target.type, spec.target.labels, spec.target.group)){
+    // `target.client` (thub run --client) accepts a resource id or name;
+    // store the id so the job stays pinned to the same Client across renames.
+    if (spec.target.client){
+      const resource = registry.get(spec.target.client) || registry.getByName(spec.target.client);
+      if (!resource){
+        throw Object.assign(new Error(`Unknown client "${spec.target.client}"`), { status: 422 });
+      }
+      spec.target.client = resource.id;
+    }
+
+    if (!registry.everSatisfiable(spec.target.type, spec.target.labels, spec.target.group, spec.target.client)){
       throw Object.assign(
         new Error(
           `No registered resource can ever satisfy type=${spec.target.type} labels=${spec.target.labels.join(',')}` +
-            (spec.target.group ? ` group=${spec.target.group}` : '')
+            (spec.target.group ? ` group=${spec.target.group}` : '') +
+            (spec.target.client ? ` client=${spec.target.client}` : '')
         ),
         { status: 422 }
       );

package/src/services/registry.js

@@ -468,21 +468,23 @@ function createRegistryService(db, { bus, events }){
     );
   }
 
-  function findIdleCandidates(type, labels, groupId){
+  function matchesTarget(r, labels, groupId, resourceId){
+    return labels.every((l) => r.labels.includes(l)) &&
+      (!groupId || r.group_ids.includes(groupId)) &&
+      (!resourceId || r.id === resourceId);
+  }
+
+  function findIdleCandidates(type, labels, groupId, resourceId){
     const rows = db
       .prepare('SELECT * FROM resources WHERE status = ? AND type = ?')
       .all(RESOURCE_STATES.IDLE, type)
       .map(rowToResource);
-    return rows.filter(
-      (r) => labels.every((l) => r.labels.includes(l)) && (!groupId || r.group_ids.includes(groupId))
-    );
+    return rows.filter((r) => matchesTarget(r, labels, groupId, resourceId));
   }
 
-  function everSatisfiable(type, labels, groupId){
+  function everSatisfiable(type, labels, groupId, resourceId){
     const rows = db.prepare('SELECT * FROM resources WHERE type = ?').all(type).map(rowToResource);
-    return rows.some(
-      (r) => labels.every((l) => r.labels.includes(l)) && (!groupId || r.group_ids.includes(groupId))
-    );
+    return rows.some((r) => matchesTarget(r, labels, groupId, resourceId));
   }
 
   return {

package/src/services/scheduler.js

@@ -1,6 +1,6 @@
 /**
  * @file        packages/coordinator/src/services/scheduler.js
- * @description Scheduler: matches queued jobs to idle resources by type/labels/group (README §5.4)
+ * @description Scheduler: matches queued jobs to idle resources by type/labels/group/client (README §5.4)
  *
  * @author      Andrian Yablonskyy
  * @copyright   Copyright (c) 2026 Andrian Yablonskyy. All rights reserved.
@@ -34,21 +34,28 @@ function createScheduler(db, { bus, events, registry, config }){
             .map(rowToJob),
 
           assignments = [],
-          claimedResourceIds = new Set();
+          claimedResourceIds = new Set(),
+          // Resources that some queued job is pinned to (`target.client`) —
+          // an unpinned job only takes one of these when nothing else fits,
+          // so it doesn't jump the pinned job's per-client queue.
+          reservedResourceIds = new Set(queued.map((j) => j.spec.target.client).filter(Boolean));
 
         for (const job of queued){
-          const candidates = registry
-            .findIdleCandidates(job.spec.target.type, job.spec.target.labels || [], job.spec.target.group)
-            .filter((r) => !claimedResourceIds.has(r.id));
+          const { type, labels = [], group, client } = job.spec.target,
+            candidates = registry
+              .findIdleCandidates(type, labels, group, client)
+              .filter((r) => !claimedResourceIds.has(r.id));
           if (candidates.length === 0){
             continue;
           }
 
-          // Least-recently-used: spread wear across benches (§5.4).
+          // Unreserved first, then least-recently-used: spread wear across benches (§5.4).
           candidates.sort((a, b) => {
-            const ta = a.last_job_finished_at ? new Date(a.last_job_finished_at).getTime() : 0,
+            const ra = reservedResourceIds.has(a.id) ? 1 : 0,
+              rb = reservedResourceIds.has(b.id) ? 1 : 0,
+              ta = a.last_job_finished_at ? new Date(a.last_job_finished_at).getTime() : 0,
               tb = b.last_job_finished_at ? new Date(b.last_job_finished_at).getTime() : 0;
-            return ta - tb;
+            return ra - rb || ta - tb;
           });
           const resource = candidates[0];
           claimedResourceIds.add(resource.id);

package/src/web/routes.js

@@ -433,6 +433,7 @@ function createWebRouter({ services, config }){
       title: job.id,
       active: 'jobs',
       job,
+      pinnedClient: job.spec.target.client ? services.registry.get(job.spec.target.client) : null,
       artifacts,
       jobActive,
       canCancel: req.session.user.role === 'admin' && jobActive

package/test/scheduler.test.js

@@ -1,6 +1,6 @@
 /**
  * @file        packages/coordinator/test/scheduler.test.js
- * @description Tests: scheduler, registry, groups, job id allocation, and admin queue operations
+ * @description Tests: scheduler, registry, groups, client pinning, job id allocation, and admin queue operations
  *
  * @author      Andrian Yablonskyy
  * @copyright   Copyright (c) 2026 Andrian Yablonskyy. All rights reserved.
@@ -349,6 +349,76 @@ test('a job with target.group is rejected (422) when no resource is ever a membe
   );
 });
 
+test('a job with target.client (by name) waits for that client even when another matching one is idle', () => {
+  const { registry, agents, jobs, scheduler } = buildTestServices(),
+    { agent } = agents.create({ name: 'ci', kind: 'ci' }),
+    pinned = registerResource(registry, { name: 'lab-pinned', type: 'sw' }),
+    other = registerResource(registry, { name: 'lab-other', type: 'sw' });
+  registry.heartbeat(other.id, { state: 'idle' }); // pinned is still REGISTERED, not IDLE
+
+  const job = jobs.create({
+    agentId: agent.id,
+    source: 'cli',
+    spec: makeSpec({ target: { type: 'sw', labels: [], client: 'lab-pinned' } })
+  });
+  assert.equal(job.spec.target.client, pinned.id); // name resolved to the stable resource id
+
+  scheduler.runPass();
+  assert.equal(jobs.get(job.id).state, JOB_STATES.QUEUED); // not grabbed by lab-other
+
+  registry.heartbeat(pinned.id, { state: 'idle' });
+  scheduler.runPass();
+  const assigned = jobs.get(job.id);
+  assert.equal(assigned.state, JOB_STATES.ASSIGNED);
+  assert.equal(assigned.resource_id, pinned.id);
+});
+
+test('an unpinned job prefers a resource no queued job is pinned to', () => {
+  const { registry, agents, jobs, scheduler } = buildTestServices(),
+    { agent } = agents.create({ name: 'ci', kind: 'ci' }),
+    pinned = registerResource(registry, { name: 'lab-pinned', type: 'sw' }),
+    other = registerResource(registry, { name: 'lab-other', type: 'sw' });
+  registry.heartbeat(pinned.id, { state: 'idle' });
+  registry.heartbeat(other.id, { state: 'idle' });
+
+  // Unpinned job has higher priority, so it's considered first; it must not
+  // take lab-pinned (which is also least-recently-used) away from the pinned job.
+  const unpinned = jobs.create({ agentId: agent.id, source: 'cli', spec: makeSpec({ priority: 90 }) }),
+    pinnedJob = jobs.create({
+      agentId: agent.id,
+      source: 'cli',
+      spec: makeSpec({ target: { type: 'sw', labels: [], client: pinned.id }, priority: 10 })
+    });
+  scheduler.runPass();
+
+  assert.equal(jobs.get(unpinned.id).resource_id, other.id);
+  assert.equal(jobs.get(pinnedJob.id).resource_id, pinned.id);
+});
+
+test('a job with target.client is rejected (422) when the client is unknown or cannot satisfy the target', () => {
+  const { registry, agents, jobs } = buildTestServices(),
+    { agent } = agents.create({ name: 'ci', kind: 'ci' });
+  registerResource(registry, { name: 'lab-sw', type: 'sw', labels: ['board:a'] });
+
+  assert.throws(
+    () => jobs.create({ agentId: agent.id, source: 'cli', spec: makeSpec({ target: { type: 'sw', client: 'nope' } }) }),
+    /Unknown client "nope"/
+  );
+  assert.throws(
+    () => jobs.create({ agentId: agent.id, source: 'cli', spec: makeSpec({ target: { type: 'hw', client: 'lab-sw' } }) }),
+    /No registered resource/
+  );
+  assert.throws(
+    () =>
+      jobs.create({
+        agentId: agent.id,
+        source: 'cli',
+        spec: makeSpec({ target: { type: 'sw', labels: ['board:b'], client: 'lab-sw' } })
+      }),
+    /No registered resource/
+  );
+});
+
 test('a resource can belong to several groups at once', () => {
   const { registry, groups } = buildTestServices(),
     g1 = groups.create({ name: 'g1' }),

package/views/jobs/show.pug

@@ -22,6 +22,9 @@ block content
     dd.col-sm-10= job.resource ? job.resource.name : '—'
     dt.col-sm-2 Target
     dd.col-sm-10= `${job.spec.target.type} — ${(job.spec.target.labels || []).join(', ')}`
+    if job.spec.target.client
+      dt.col-sm-2 Client
+      dd.col-sm-10= pinnedClient ? pinnedClient.name : job.spec.target.client
     dt.col-sm-2 Created
     dd.col-sm-10= fmtDate(job.created_at)
     if job.message