@andrian.yablonskyy/thub-coordinator 1.1.6 → 1.1.8

package/bin/thub-admin.js

@@ -342,7 +342,7 @@ function main(){
       return usage(), process.exit(4);
     }
     const group = groups.create({ name, comment: flags.comment });
-    console.log(`Group ${group.id} created ("${group.name}"). Use it with: thub run --group ${group.id}`);
+    console.log(`Group ${group.id} created ("${group.name}"). Give it to users or CI tokens on the dashboard (Users / CI tokens).`);
     return;
   }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@andrian.yablonskyy/thub-coordinator",
-  "version": "1.1.6",
+  "version": "1.1.8",
   "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.1",
+    "@andrian.yablonskyy/thub-common": "^1.1.2",
     "better-sqlite3": "^12.4.1",
     "express": "^5.1.0",
     "express-session": "^1.18.2",

package/src/api/agent.js

@@ -106,13 +106,17 @@ function createAgentRouter({ services, config }){
 
   // `thub whoami` / `thub key show` (§10.3): who this key belongs to.
   router.get('/me', auth, (req, res) => {
+    // The group its jobs run in (set on the dashboard, §13.1), by name.
+    const groupId = req.user ? services.adminUsers.getById(req.user.id)?.groupId : services.agents.get(req.agent.id)?.group_id,
+      group = groupId ? services.groups.get(groupId)?.name || null : null;
     if (!req.user){
-      return res.json({ kind: req.agent.kind, name: req.agent.name });
+      return res.json({ kind: req.agent.kind, name: req.agent.name, group });
     }
     const { username, email, role } = req.user,
       key = services.adminUsers.keyOf(req.user.id);
     res.json({
       kind: req.agent.kind,
+      group,
       user: { username, email, role },
       key: { hint: key.token_hint, createdAt: key.token_created_at || key.created_at, lastUsedAt: key.last_used_at }
     });

package/src/db/migrations/028_agent_groups.sql

@@ -0,0 +1,5 @@
+-- The resource group an agent's jobs run in (§13.1), set on the dashboard
+-- only — no longer `thub run --group`: a user's (Users, kept across key
+-- rotations) or a CI token's (CI tokens). NULL: any resource.
+ALTER TABLE users ADD COLUMN group_id TEXT;
+ALTER TABLE agents ADD COLUMN group_id TEXT;

package/src/db/migrations/029_agent_deleted.sql

@@ -0,0 +1,3 @@
+-- Deleting a CI token (dashboard): its token stops working and it leaves the
+-- CI tokens list, but the row stays — its jobs reference it and keep its name.
+ALTER TABLE agents ADD COLUMN deleted_at TEXT;

package/src/services/admin-users.js

@@ -101,6 +101,7 @@ function toProfile(row){
     theme: row.theme,
     sessionTimeoutMin: row.session_timeout_min,
     listPrefs: parseListPrefs(row.list_prefs),
+    groupId: row.group_id || null,
     blocked: Boolean(row.blocked_at),
     blockedAt: row.blocked_at || null,
     mustChangePassword: Boolean(row.must_change_password),
@@ -211,17 +212,30 @@ function createAdminUsersService(db, { events } = {}){
   // callers may leave it out — the Users page flags a missing one.
   // A dashboard role without a password gets a temporary one, returned
   // once, to be changed at the first sign-in.
-  function create({ username, email, role, password, firstName, lastName, requireEmail = false }, { by } = {}){
+  // The resource group a user's jobs run in (§13.1): an existing group's id,
+  // or null for any resource.
+  function checkGroup(groupId){
+    if (!groupId){
+      return null;
+    }
+    if (!db.prepare('SELECT 1 FROM groups WHERE id = ?').get(groupId)){
+      throw bad('Unknown group');
+    }
+    return groupId;
+  }
+
+  function create({ username, email, role, password, firstName, lastName, groupId, requireEmail = false }, { by } = {}){
     const id = `usr_${uuid()}`,
+      group = checkGroup(groupId),
       name = checkUsername(username),
       r = normalizeRole(role),
       mail = email || requireEmail ? checkEmail(email) : '',
       temp = !password && DASHBOARD_ROLES.includes(r) ? tempPassword() : null,
       pw = password || temp;
     db.prepare(
-      `INSERT INTO users (id, username, email, password_hash, role, first_name, last_name, must_change_password, created_at)
-       VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)`
-    ).run(id, name, mail, pw ? hashPassword(pw) : null, r, firstName || null, lastName || null, temp ? 1 : 0, new Date().toISOString());
+      `INSERT INTO users (id, username, email, password_hash, role, first_name, last_name, must_change_password, group_id, created_at)
+       VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`
+    ).run(id, name, mail, pw ? hashPassword(pw) : null, r, firstName || null, lastName || null, temp ? 1 : 0, group, new Date().toISOString());
     audit(id, 'user.created', { by, username: name, role: r });
     return { id, username: name, role: r, tempPassword: temp };
   }
@@ -292,14 +306,15 @@ function createAdminUsersService(db, { events } = {}){
       email: fields.email !== undefined ? checkEmail(fields.email, id) : target.email,
       role: fields.role !== undefined ? normalizeRole(fields.role) : target.role,
       first_name: fields.firstName !== undefined ? fields.firstName || null : target.first_name,
-      last_name: fields.lastName !== undefined ? fields.lastName || null : target.last_name
+      last_name: fields.lastName !== undefined ? fields.lastName || null : target.last_name,
+      group_id: fields.groupId !== undefined ? checkGroup(fields.groupId) : target.group_id
     };
     guardAdmins(target, { actorId, losesAdmin: next.role !== 'admin' });
     // Promoted to the dashboard without a password: a temporary one.
     const temp = DASHBOARD_ROLES.includes(next.role) && !target.password_hash ? tempPassword() : null;
     db.transaction(() => {
-      db.prepare('UPDATE users SET username = ?, email = ?, role = ?, first_name = ?, last_name = ? WHERE id = ?')
-        .run(next.username, next.email, next.role, next.first_name, next.last_name, id);
+      db.prepare('UPDATE users SET username = ?, email = ?, role = ?, first_name = ?, last_name = ?, group_id = ? WHERE id = ?')
+        .run(next.username, next.email, next.role, next.first_name, next.last_name, next.group_id, id);
       if (temp){
         db.prepare('UPDATE users SET password_hash = ?, must_change_password = 1 WHERE id = ?').run(hashPassword(temp), id);
       }

package/src/services/agents.js

@@ -29,7 +29,8 @@ function createAgentsService(db, { events }){
   }
 
   function list(){
-    return db.prepare('SELECT id, name, kind, user_id, version, update_to, created_at, last_used_at, revoked_at FROM agents ORDER BY created_at DESC').all();
+    return db.prepare(`SELECT id, name, kind, user_id, group_id, version, update_to, created_at, last_used_at, revoked_at, token_created_at
+                       FROM agents WHERE deleted_at IS NULL ORDER BY created_at DESC`).all();
   }
 
   function create({ name, kind }){
@@ -60,6 +61,57 @@ function createAgentsService(db, { events }){
     return get(id);
   }
 
+  // The resource group a CI token's jobs run in (§13.1), set on CI tokens:
+  // an existing group's id, or null for any resource.
+  function setGroup(id, groupId){
+    const agent = get(id);
+    if (!agent){
+      throw Object.assign(new Error('Unknown agent'), { status: 404 });
+    }
+    const group = groupId || null;
+    if (group && !db.prepare('SELECT 1 FROM groups WHERE id = ?').get(group)){
+      throw Object.assign(new Error('Unknown group'), { status: 400 });
+    }
+    if (group !== (agent.group_id || null)){
+      db.prepare('UPDATE agents SET group_id = ? WHERE id = ?').run(group, id);
+      events.record('agent', id, 'agent.group_set', { from: agent.group_id || null, to: group });
+    }
+    return get(id);
+  }
+
+  // CI tokens page: a new token for the same agent — the old one stops
+  // working at once (a revoked token comes back with it). Returned once;
+  // the row, and so its jobs and name, stay the same.
+  function rotateToken(id){
+    const agent = get(id);
+    if (!agent || agent.deleted_at){
+      throw Object.assign(new Error('Unknown agent'), { status: 404 });
+    }
+    if (agent.user_id){
+      throw Object.assign(new Error('A user\'s key is replaced on Users, not here'), { status: 400 });
+    }
+    const token = generateToken('agt');
+    db.prepare('UPDATE agents SET token_hash = ?, token_created_at = ?, revoked_at = NULL WHERE id = ?').run(hashToken(token), new Date().toISOString(), id);
+    events.record('agent', id, 'agent.token_rotated', { name: agent.name });
+    return token;
+  }
+
+  // CI tokens page: gone from the list, its token revoked; the row stays for
+  // the jobs that reference it (they keep showing its name).
+  function remove(id){
+    const agent = get(id);
+    if (!agent || agent.deleted_at){
+      throw Object.assign(new Error('Unknown agent'), { status: 404 });
+    }
+    if (agent.user_id){
+      throw Object.assign(new Error('A user\'s key is managed on Users, not here'), { status: 400 });
+    }
+    const now = new Date().toISOString();
+    db.prepare('UPDATE agents SET deleted_at = ?, revoked_at = COALESCE(revoked_at, ?), update_to = NULL WHERE id = ?').run(now, now, id);
+    events.record('agent', id, 'agent.deleted', { name: agent.name });
+    return agent;
+  }
+
   function revoke(id){
     db.prepare('UPDATE agents SET revoked_at = ? WHERE id = ?').run(new Date().toISOString(), id);
     events.record('agent', id, 'agent.revoked', {});
@@ -97,7 +149,7 @@ function createAgentsService(db, { events }){
     return ids.length;
   }
 
-  return { get, getByTokenHash, list, create, rename, revoke, touchLastUsed, setUpdateTo, requestUpdateAll };
+  return { get, getByTokenHash, list, create, rename, setGroup, rotateToken, remove, revoke, touchLastUsed, setUpdateTo, requestUpdateAll };
 }
 
 module.exports = { createAgentsService };

package/src/services/groups.js

@@ -15,9 +15,10 @@
 
 const { v4: uuid } = require('uuid');
 
-// Admin-managed resource groups (README §13.1) — a job can be constrained
-// to run only on resources that are members of a given group
-// (`thub run --group <id>`, job-spec.schema.js's `target.group`).
+// Admin-managed resource groups (README §13.1). An agent — a user, or a CI
+// token — may be given one on the dashboard; its jobs then run only on
+// resources that are members of it (job-spec.schema.js's `target.group`,
+// filled in by jobs.create — never taken from the Agent).
 // Membership itself lives on the resource (registry.js's `group_ids`,
 // declared by the Client's own config), not here — this service only
 // owns the groups' own identity (id/name/comment).
@@ -69,6 +70,9 @@ function createGroupsService(db, { events, registry }){
         registry.setGroups(resource.id, resource.group_ids.filter((g) => g !== id));
       }
     }
+    // Agents in it go back to running anywhere.
+    db.prepare('UPDATE users SET group_id = NULL WHERE group_id = ?').run(id);
+    db.prepare('UPDATE agents SET group_id = NULL WHERE group_id = ?').run(id);
     db.prepare('DELETE FROM groups WHERE id = ?').run(id);
     events.record('group', id, 'group.deleted', { name: group.name });
   }

package/src/services/jobs.js

@@ -141,6 +141,15 @@ function createJobsService(db, { bus, events, registry, config }){
     return { rows: rows.map(rowToJob), pagination };
   }
 
+  // The group an agent's jobs run in: its user's, or the CI token's own.
+  function agentGroup(agentId){
+    return db.prepare(
+      `SELECT g.id, g.name FROM agents a LEFT JOIN users u ON u.id = a.user_id
+       JOIN groups g ON g.id = CASE WHEN a.user_id IS NOT NULL THEN u.group_id ELSE a.group_id END
+       WHERE a.id = ?`
+    ).get(agentId) || null;
+  }
+
   function countQueuedForAgent(agentId){
     return db
       .prepare('SELECT COUNT(*) AS n FROM jobs WHERE agent_id = ? AND state IN (\'QUEUED\',\'ASSIGNED\')')
@@ -157,6 +166,13 @@ function createJobsService(db, { bus, events, registry, config }){
       throw Object.assign(new Error(`Invalid job spec (${VERSIONS}): ${errors.join('; ')}`), { status: 400 });
     }
     spec.source = source;
+    // The group is the agent's, set on the dashboard (§13.1) — whatever an
+    // older Agent sent as `target.group` is replaced.
+    const group = agentGroup(agentId);
+    delete spec.target.group;
+    if (group){
+      spec.target.group = group.id;
+    }
 
     // `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.
@@ -168,12 +184,12 @@ function createJobsService(db, { bus, events, registry, config }){
       spec.target.client = resource.id;
     }
 
-    const { type, labels, group, client } = spec.target;
-    if (!registry.everSatisfiable(type, labels, group, client)){
+    const { type, labels, group: groupId, client } = spec.target;
+    if (!registry.everSatisfiable(type, labels, groupId, 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}` : '') +
+            (group ? ` group=${group.name} (this agent's group, set on the dashboard)` : '') +
             (spec.target.client ? ` client=${spec.target.client}` : '')
         ),
         { status: 422 }

package/src/services/list-prefs.js

@@ -32,11 +32,11 @@ const PAGE_SIZES = [10, 25, 50, 100, 'all'],
       defaults: { size: DEFAULT_PAGE_SIZE, sort: 'name', dir: 'asc' }
     },
     agents: {
-      sorts: ['name', 'kind', 'version', 'created', 'used', 'status'],
+      sorts: ['name', 'kind', 'group', 'version', 'created', 'used', 'status'],
       defaults: { size: DEFAULT_PAGE_SIZE, sort: 'created', dir: 'desc' }
     },
     users: {
-      sorts: ['username', 'role', 'status', 'used'],
+      sorts: ['username', 'role', 'group', 'status', 'used'],
       defaults: { size: DEFAULT_PAGE_SIZE, sort: 'username', dir: 'asc' }
     }
   };

package/src/web/routes.js

@@ -955,6 +955,7 @@ function createWebRouter({ services, config }){
       active: 'jobs',
       job,
       pinnedClient: job.spec.target.client ? services.registry.get(job.spec.target.client) : null,
+      targetGroup: job.spec.target.group ? services.groups.get(job.spec.target.group) : null,
       waitingReason: job.state === JOB_STATES.QUEUED
         ? services.registry.waitingReason(job.spec.target.type, job.spec.target.labels || [], job.spec.target.group,
           job.spec.target.client)
@@ -1033,10 +1034,19 @@ function createWebRouter({ services, config }){
     const q = search.normalizeQuery(req.query.q),
       terms = search.parseTerms(q),
       resources = services.registry.list(),
+      // Who runs their jobs in each group: users, and CI tokens still in use.
+      agentsIn = [
+        ...services.adminUsers.list().map((u) => ({ name: u.username, groupId: u.groupId })),
+        ...services.agents.list().filter((a) => !a.user_id && !a.revoked_at).map((a) => ({ name: a.name, groupId: a.group_id }))
+      ],
       all = services.groups.list(),
       groups = all
-        .filter((g) => search.matches([g.id, g.name, g.comment], terms))
-        .map((g) => ({ ...g, resourceCount: resources.filter((r) => r.group_ids.includes(g.id)).length }));
+        .filter((g) => search.matches([g.name, g.comment], terms))
+        .map((g) => ({
+          ...g,
+          resourceCount: resources.filter((r) => r.group_ids.includes(g.id)).length,
+          agentNames: agentsIn.filter((a) => a.groupId === g.id).map((a) => a.name)
+        }));
     res.render('groups/list', {
       title: 'Groups',
       active: 'groups',
@@ -1070,11 +1080,13 @@ function createWebRouter({ services, config }){
       terms = search.parseTerms(q),
       view = listView(req, res, 'agents', { q }),
       { sort, dir, size } = view.prefs,
-      value = AGENT_SORT_VALUE[sort],
+      groupsById = Object.fromEntries(services.groups.list().map((g) => [g.id, g])),
+      groupName = (a) => groupsById[a.group_id]?.name || null,
+      value = sort === 'group' ? groupName : AGENT_SORT_VALUE[sort],
       // CI tokens only: a person's key belongs to their user (Users, §10.3).
       sorted = services.agents.list()
         .filter((a) => !a.user_id)
-        .filter((a) => search.matches([a.id, a.name, a.kind, a.version, a.revoked_at ? 'revoked' : 'active'], terms))
+        .filter((a) => search.matches([a.name, a.kind, a.version, groupName(a), a.revoked_at ? 'revoked' : 'active'], terms))
         .sort((a, b) => {
           const va = value(a),
             vb = value(b);
@@ -1090,6 +1102,8 @@ function createWebRouter({ services, config }){
       active: 'agents',
       liveTopics: 'agents',
       agents: sorted.slice(pagination.offset, pagination.offset + pagination.limit),
+      groups: services.groups.list(),
+      groupsById,
       q,
       list: { ...view, pagination, pageUrl, q },
       ...extra
@@ -1200,6 +1214,7 @@ function createWebRouter({ services, config }){
       username: (u) => userDisplayName(u).toLowerCase(),
       role: (u) => ROLE_ORDER[u.role],
       status: (u) => (u.blocked ? 1 : 0),
+      group: (u) => (u.groupId ? services.groups.get(u.groupId)?.name.toLowerCase() : null) || null,
       used: (u) => u.key?.lastUsedAt || null
     },
     // Who manages whom on Users (§10.3): an admin everyone; a maintainer
@@ -1210,7 +1225,7 @@ function createWebRouter({ services, config }){
     managesUser = (actor, u) => Boolean(u) && (isAdmin(actor) || u.role === 'user' || u.id === actor.id),
     userFiltersFor = (actor) => (isAdmin(actor) ? USER_ROLE_FILTERS : ['user', 'blocked']),
     // The audit log's Action column names changed fields like this.
-    FIELD_LABEL = { username: 'username', email: 'email', role: 'role', first_name: 'first name', last_name: 'last name' };
+    FIELD_LABEL = { username: 'username', email: 'email', role: 'role', first_name: 'first name', last_name: 'last name', group_id: 'group' };
 
   // The audit log's Action column: what was done, to whom. `nameOf` gives
   // the account's current username (else the one its events recorded).
@@ -1283,7 +1298,8 @@ function createWebRouter({ services, config }){
       visible = services.adminUsers.list().filter((u) => managesUser(me, u)),
       visibleIds = new Set(visible.map((u) => u.id)),
       searched = visible
-        .filter((u) => search.matches([u.username, u.email, u.firstName, u.lastName, u.role, u.blocked ? 'blocked' : 'active'], terms)),
+        .filter((u) => search.matches([u.username, u.email, u.firstName, u.lastName, u.role, services.groups.get(u.groupId)?.name,
+          u.blocked ? 'blocked' : 'active'], terms)),
       // Counts for the filter buttons: within the search, before the role filter.
       roleCounts = Object.fromEntries(filters.map((r) => [r, searched.filter((u) => (r === 'blocked' ? u.blocked : u.role === r)).length])),
       sorted = searched
@@ -1314,6 +1330,8 @@ function createWebRouter({ services, config }){
       me,
       // The roles this admin or maintainer may give.
       roles: isAdmin(me) ? services.adminUsers.ROLES : ['user'],
+      groups: services.groups.list(),
+      groupsById: Object.fromEntries(services.groups.list().map((g) => [g.id, g])),
       roleHelp: {
         user: 'Agent only: submits jobs, reads their own results; no dashboard',
         maintainer: 'Agent + the dashboard without Settings; manages Agent-only users and CI tokens; sees and cancels every job',
@@ -1359,12 +1377,12 @@ function createWebRouter({ services, config }){
   router.get('/admin/users', (req, res) => renderUsers(req, res));
 
   router.post('/admin/users', userAction((req, ctx) => {
-    const { username, email, role, firstName, lastName } = req.body;
+    const { username, email, role, firstName, lastName, groupId } = req.body;
     if (!isAdmin(ctx.actor) && normalizeRole(role) !== 'user'){
       throw new Error('Only an admin can create a maintainer or an admin.');
     }
     const
-      created = services.adminUsers.create({ username, email, role, firstName, lastName, requireEmail: true }, ctx),
+      created = services.adminUsers.create({ username, email, role, firstName, lastName, groupId, requireEmail: true }, ctx),
       key = req.body.issueKey === '1' ? services.adminUsers.issueKey(created.id, ctx) : null;
     if (!key && !created.tempPassword){
       return { message: `User ${created.username} created.` };
@@ -1373,12 +1391,12 @@ function createWebRouter({ services, config }){
   }));
 
   router.post('/admin/users/:id', userAction((req, ctx) => {
-    const { username, email, role, firstName, lastName } = req.body;
+    const { username, email, role, firstName, lastName, groupId } = req.body;
     if (!isAdmin(ctx.actor) && role !== undefined && normalizeRole(role) !== services.adminUsers.getById(req.params.id).role){
       throw new Error('Only an admin can change a role.');
     }
     const
-      { user, tempPassword } = services.adminUsers.update(req.params.id, { username, email, role, firstName, lastName }, ctx);
+      { user, tempPassword } = services.adminUsers.update(req.params.id, { username, email, role, firstName, lastName, groupId }, ctx);
     return tempPassword
       ? { secret: { title: `${user.username} can now use the dashboard`, password: tempPassword, username: user.username } }
       : { message: `Saved ${user.username}.` };
@@ -1430,17 +1448,52 @@ function createWebRouter({ services, config }){
 
   router.post('/admin/agents', (req, res) => {
     // CI tokens only; people get their key from their user (§10.3).
-    const { token } = services.agents.create({ name: req.body.name, kind: 'ci' });
-    renderAgents(req, res, { newToken: token });
+    try {
+      const { agent, token } = services.agents.create({ name: req.body.name, kind: 'ci' });
+      services.agents.setGroup(agent.id, req.body.groupId);
+      renderAgents(req, res, { newToken: token });
+    }
+    catch (err){
+      flash(req, 'danger', err.message);
+      res.redirect('/admin/agents');
+    }
   });
 
   router.post('/admin/agents/:id/rename', (req, res) => {
     try {
-      const before = services.agents.get(req.params.id)?.name,
+      const before = services.agents.get(req.params.id),
         agent = services.agents.rename(req.params.id, req.body.name);
-      if (before !== agent.name){
-        flash(req, 'success', `Renamed agent "${before}" to "${agent.name}".`);
+      if (before.name !== agent.name){
+        flash(req, 'success', `Renamed agent "${before.name}" to "${agent.name}".`);
       }
+      if (req.body.groupId !== undefined && (req.body.groupId || null) !== (before.group_id || null)){
+        const group = req.body.groupId ? services.groups.get(req.body.groupId) : null;
+        services.agents.setGroup(req.params.id, req.body.groupId);
+        flash(req, 'success', group ? `"${agent.name}" now runs its jobs in group ${group.name}.` : `"${agent.name}" now runs its jobs on any resource.`);
+      }
+    }
+    catch (err){
+      flash(req, 'danger', err.message);
+    }
+    res.redirect(returnTo(req, '/admin/agents'));
+  });
+
+  router.post('/admin/agents/:id/token', (req, res) => {
+    try {
+      const agent = services.agents.get(req.params.id),
+        token = services.agents.rotateToken(req.params.id);
+      return renderAgents(req, res, { newToken: token, newTokenFor: agent.name });
+    }
+    catch (err){
+      flash(req, 'danger', err.message);
+    }
+    res.redirect(returnTo(req, '/admin/agents'));
+  });
+
+  router.post('/admin/agents/:id/delete', (req, res) => {
+    try {
+      const agent = services.agents.remove(req.params.id);
+      flash(req, 'success', `Deleted CI token "${agent.name}". Its jobs stay, listed under its name.`);
     }
     catch (err){
       flash(req, 'danger', err.message);

package/test/groups-tab.test.js

@@ -205,3 +205,73 @@ test('resource card CSS: stacked tabs let only the visible one take the mouse (e
   assert.match(off, /^[^{]*> form > fieldset,[^{]*\.tab-pane \{\s*pointer-events: none;/);
   assert.match(css, /\.thub-resource-card \.tab-content \.tab-pane\.active \{[^}]*pointer-events: auto;/);
 });
+
+test('agent groups are set on the dashboard (Users, CI tokens) and shown by name — never a group id', async (t) => {
+  const { base, services, admin, viewer } = await start(t),
+    g = services.groups.create({ name: 'nightly-pool', comment: 'night runs' }),
+    form = (cookie, p, body) => fetch(`${base}${p}`, { method: 'POST', headers: { cookie }, body: new URLSearchParams(body), redirect: 'manual' }),
+    page = async (cookie, p) => (await fetch(`${base}${p}`, { headers: { cookie } })).text();
+  services.registry.registerAuto({ clientId: 'sw9', name: 'lab-sw-09', type: 'sw', labels: [], groups: [g.id] });
+
+  // A maintainer puts an Agent-only user in the group, an admin a CI token.
+  await form(viewer, '/admin/users', { username: 'dev', email: 'd@example.com', role: 'user', groupId: g.id });
+  const dev = services.adminUsers.getByUsername('dev');
+  assert.equal(services.adminUsers.getById(dev.id).groupId, g.id);
+  await form(admin, '/admin/agents', { name: 'ci-night', groupId: g.id });
+  const ci = services.agents.list().find((a) => a.name === 'ci-night');
+  assert.equal(ci.group_id, g.id);
+  await form(admin, `/admin/agents/${ci.id}/rename`, { name: 'ci-night', groupId: '' });
+  assert.equal(services.agents.get(ci.id).group_id, null);
+  await form(admin, `/admin/agents/${ci.id}/rename`, { name: 'ci-night', groupId: g.id });
+
+  // A job from the user lands in the group; its page names it.
+  services.adminUsers.issueKey(dev.id, { by: 'admin' });
+  const devAgent = services.agents.list().find((a) => a.user_id === dev.id),
+    job = services.jobs.create({ agentId: devAgent.id, source: 'cli', spec: { target: { type: 'sw', labels: [] }, command: './t.sh' } });
+  assert.match(await page(admin, `/jobs/${job.id}`), /<dt class="col-sm-2">Group<\/dt><dd class="col-sm-10">nightly-pool<\/dd>/);
+
+  const users = await page(admin, '/admin/users'),
+    agents = await page(admin, '/admin/agents'),
+    groups = await page(admin, '/groups');
+  assert.match(users, /<span class="badge text-bg-info">nightly-pool<\/span>/);
+  assert.match(users, new RegExp(`<option value="${g.id}" selected="selected">nightly-pool</option>`)); // the picker (a value, not shown)
+  assert.match(agents, /<span class="badge text-bg-info">nightly-pool<\/span>/);
+  assert.match(groups, /data-bs-title="dev, ci-night"[^>]*>2</); // Agents column: users, then CI tokens
+  // The id is never shown as text on a page (it's only in values and URLs).
+  for (const html of [users, agents, groups, await page(admin, '/resources'), await page(admin, `/jobs/${job.id}`)]){
+    const text = html.replace(/<[^>]*>/g, ' ');
+    assert.ok(!text.includes(g.id), 'a group id shows as text');
+  }
+});
+
+test('CI tokens: the name opens Edit; a new token replaces the old one; delete keeps its jobs', async (t) => {
+  const { base, services, admin } = await start(t),
+    form = (p, body = {}) => fetch(`${base}${p}`, { method: 'POST', headers: { cookie: admin }, body: new URLSearchParams(body), redirect: 'manual' }),
+    { agent, token } = services.agents.create({ name: 'ci-fw', kind: 'ci' }),
+    me = (tok) => fetch(`${base}/api/v1/me`, { headers: { authorization: `Bearer ${tok}` } });
+  services.registry.registerAuto({ clientId: 'sw7', name: 'lab-sw-07', type: 'sw', labels: [] });
+  const job = services.jobs.create({ agentId: agent.id, source: 'ci', spec: { target: { type: 'sw', labels: [] }, command: './t.sh' } });
+
+  let html = await (await fetch(`${base}/admin/agents`, { headers: { cookie: admin } })).text();
+  assert.match(html, new RegExp(`<a class="fw-medium" href="#editAgentModal-${agent.id}" data-bs-toggle="modal" role="button">ci-fw</a>`));
+  assert.doesNotMatch(html, />Edit<\/button>/);
+
+  // New token: shown once, the old one stops at once.
+  const res = await form(`/admin/agents/${agent.id}/token`);
+  html = await res.text();
+  const fresh = /value="(agt_[^"]+)" readonly/.exec(html)?.[1];
+  assert.ok(fresh, 'the new token is shown');
+  assert.match(html, /New token for ci-fw \(shown once — the old one has stopped working\)/);
+  assert.equal((await me(token)).status, 401);
+  assert.equal((await me(fresh)).status, 200);
+
+  // Delete: gone from the list and from the API; its job keeps its name.
+  await form(`/admin/agents/${agent.id}/delete`);
+  html = await (await fetch(`${base}/admin/agents`, { headers: { cookie: admin } })).text();
+  assert.match(html, /Deleted CI token &quot;ci-fw&quot;|Deleted CI token "ci-fw"/); // the flash
+  assert.doesNotMatch(html.slice(html.indexOf('<tbody')), /ci-fw/); // the list
+  assert.equal((await me(fresh)).status, 401);
+  assert.ok((await (await fetch(`${base}/jobs?q=ci-fw`, { headers: { cookie: admin } })).text()).includes(job.id)); // still found by its name
+  assert.match(await (await form(`/admin/agents/${agent.id}/token`)).headers.get('location'), /agents/); // can't come back
+  assert.equal(services.agents.get(agent.id).revoked_at !== null, true);
+});

package/test/scheduler.test.js

@@ -25,6 +25,7 @@ const test = require('node:test'),
   { createRegistryService } = require('../src/services/registry'),
   { createAgentsService } = require('../src/services/agents'),
   { createGroupsService } = require('../src/services/groups'),
+  { createAdminUsersService } = require('../src/services/admin-users'),
   { createJobsService } = require('../src/services/jobs'),
   { createLogsService } = require('../src/services/logs'),
   { createScheduler } = require('../src/services/scheduler'),
@@ -334,43 +335,52 @@ test('a legacy resource with no clientId (pre-dates the feature) is adopted by n
   assert.equal(registry.list().length, 1);
 });
 
-test('a job with target.group only schedules onto resources that are members of that group', () => {
-  const { registry, agents, groups, jobs, scheduler } = buildTestServices(),
+test('an agent given a group (dashboard) runs its jobs only on that group\'s resources; whatever the Agent sends is replaced', () => {
+  const { db, registry, agents, groups, jobs, scheduler } = buildTestServices(),
+    users = createAdminUsersService(db, {}),
     { agent } = agents.create({ name: 'ci', kind: 'ci' }),
     groupA = groups.create({ name: 'group-a' }),
     groupB = groups.create({ name: 'group-b' }),
-
     inGroupA = registerResource(registry, { name: 'lab-a', type: 'sw', groups: [groupA.id] }),
     inGroupB = registerResource(registry, { name: 'lab-b', type: 'sw', groups: [groupB.id] });
   registry.heartbeat(inGroupA.id, { state: 'idle' });
   registry.heartbeat(inGroupB.id, { state: 'idle' });
 
-  const job = jobs.create({
-    agentId: agent.id,
-    source: 'cli',
-    spec: makeSpec({ target: { type: 'sw', labels: [], group: groupA.id } })
-  });
+  // A CI token in group B, whose (older) Agent still asks for group A.
+  agents.setGroup(agent.id, groupB.id);
+  const job = jobs.create({ agentId: agent.id, source: 'ci', spec: makeSpec({ target: { type: 'sw', labels: [], group: groupA.id } }) });
+  assert.equal(jobs.get(job.id).spec.target.group, groupB.id);
   scheduler.runPass();
-
-  const assigned = jobs.get(job.id);
-  assert.equal(assigned.state, JOB_STATES.ASSIGNED);
-  assert.equal(assigned.resource_id, inGroupA.id); // not inGroupB, despite being IDLE and type-matching
-});
-
-test('a job with target.group is rejected (422) when no resource is ever a member of that group', () => {
+  assert.equal(jobs.get(job.id).resource_id, inGroupB.id);
+
+  // A user's group follows their key (kept across rotations); none = any resource.
+  const dev = users.create({ username: 'dev', email: 'd@example.com', role: 'user', groupId: groupA.id }, { by: 't' });
+  users.issueKey(dev.id, { by: 't' });
+  const devAgent = agents.list().find((a) => a.user_id === dev.id),
+    devJob = jobs.create({ agentId: devAgent.id, source: 'cli', spec: makeSpec({ target: { type: 'sw', labels: [] } }) });
+  assert.equal(jobs.get(devJob.id).spec.target.group, groupA.id);
+  users.issueKey(dev.id, { by: 't' }); // rotated
+  const rotatedJob = jobs.create({ agentId: devAgent.id, source: 'cli', spec: makeSpec({ target: { type: 'sw', labels: [] } }) });
+  assert.equal(jobs.get(rotatedJob.id).spec.target.group, groupA.id);
+  users.update(dev.id, { groupId: '' }, { by: 't' });
+  const anyJob = jobs.create({ agentId: devAgent.id, source: 'cli', spec: makeSpec({ target: { type: 'sw', labels: [] } }) });
+  assert.equal(jobs.get(anyJob.id).spec.target.group, undefined);
+
+  // Deleting a group sends its agents back to any resource.
+  groups.remove(groupB.id);
+  assert.equal(agents.get(agent.id).group_id, null);
+  assert.throws(() => agents.setGroup(agent.id, 'no-such-group'), /Unknown group/);
+});
+
+test('a job is rejected (422) when no resource is ever a member of its agent\'s group — named, not by id', () => {
   const { registry, agents, groups, jobs } = buildTestServices(),
     { agent } = agents.create({ name: 'ci', kind: 'ci' }),
     group = groups.create({ name: 'empty-group' });
   registerResource(registry, { name: 'lab-01', type: 'sw', groups: [] }); // exists, but not a member
-
+  agents.setGroup(agent.id, group.id);
   assert.throws(
-    () =>
-      jobs.create({
-        agentId: agent.id,
-        source: 'cli',
-        spec: makeSpec({ target: { type: 'sw', labels: [], group: group.id } })
-      }),
-    /No registered resource/
+    () => jobs.create({ agentId: agent.id, source: 'cli', spec: makeSpec({ target: { type: 'sw', labels: [] } }) }),
+    /No registered resource can ever satisfy type=sw labels= group=empty-group \(this agent's group, set on the dashboard\)/
   );
 });
 

package/test/users.test.js

@@ -358,7 +358,7 @@ test('maintainers manage Agent-only users, their own account and CI tokens — n
 
   // CI tokens: issue, rename, revoke.
   page = await post('/admin/agents', { name: 'ci-nightly' });
-  assert.match(page, /Token \(shown once\):[\s\S]*?<code>agt_/);
+  assert.match(page, /Token \(shown once\):[\s\S]*?value="agt_/);
   const ci = services.agents.list().find((a) => a.name === 'ci-nightly');
   await post(`/admin/agents/${ci.id}/rename`, { name: 'ci-night' });
   await post(`/admin/agents/${ci.id}/revoke`);
@@ -423,7 +423,7 @@ test('audit log: Timestamp, User (who did it — always), Action — from the da
     log = html.slice(html.indexOf('Recent activity'), html.indexOf('id="addUserModal"')),
     rows = [...log.matchAll(/<tr><td[^>]*>[^<]*<\/td><td[^>]*>([^<]*)<\/td><td>([^<]*)<\/td><\/tr>/g)]
       .map((m) => [m[1], m[2].replace(/&#39;/g, '\'').replace(/&gt;/g, '>')]).reverse(); // oldest first
-  assert.match(log, /<th class="text-nowrap">Timestamp<\/th><th>User<\/th><th>Action<\/th>/);
+  assert.match(log, /<th[^>]*>Timestamp<\/th><th>User<\/th><th>Action<\/th>/);
   assert.deepEqual(rows, [
     ['root', 'Created root (Admin)'],
     ['root', 'Created dev (User)'],

package/views/admin/agents.pug

@@ -1,5 +1,6 @@
 extends ../layout
 include ../mixins/updates
+include ../mixins/group-select
 include ../mixins/list-controls
 
 block content
@@ -9,15 +10,18 @@ block content
   .d-flex.flex-wrap.align-items-center.gap-2.mb-3
     +updatesToolbar('agent', 'agents', list.pageUrl())
   .d-flex.flex-wrap.align-items-center.gap-2.mb-3
-    +searchForm(q, 'Search agents: name, kind, version, status', list.urlFor({ q: '' }))
+    +searchForm(q, 'Search agents: name, kind, group, version, status', list.urlFor({ q: '' }))
     .ms-auto
       +pageSizePicker(list)
 
   if newToken
-    .alert.alert-warning
-      strong Token (shown once):
-      |
-      code= newToken
+    //- Shown once: nothing below keeps it.
+    .alert.alert-warning(role="alert")
+      strong= newTokenFor ? `New token for ${newTokenFor} (shown once — the old one has stopped working):` : 'Token (shown once):'
+      .input-group.input-group-sm.mt-2
+        input.form-control.font-monospace(type="text" value=newToken readonly aria-label="Token")
+        button.btn.btn-outline-secondary(type="button" data-copy=newToken aria-label="Copy token")
+          i.bi.bi-clipboard
 
   div(data-live="list-toolbar")
     +listToolbar(list, 'agents')
@@ -27,6 +31,7 @@ block content
       tr
         +sortHeader(list, 'name', 'Name')
         +sortHeader(list, 'kind', 'Kind')
+        +sortHeader(list, 'group', 'Group')
         +sortHeader(list, 'version', 'Version', 'desc')
         +sortHeader(list, 'created', 'Created', 'desc')
         +sortHeader(list, 'used', 'Last used', 'desc')
@@ -35,21 +40,33 @@ block content
     tbody(data-live="rows")
       each a in agents
         tr(class=a.revoked_at ? 'opacity-50' : '')
-          td= a.name
+          //- The name opens Edit (name and group).
+          td
+            a.fw-medium(href=`#editAgentModal-${a.id}` data-bs-toggle="modal" role="button")= a.name
           td.text-uppercase= a.kind
+          td
+            if a.group_id && groupsById[a.group_id]
+              span.badge.text-bg-info= groupsById[a.group_id].name
+            else
+              span.text-body-secondary any
           //- A revoked token can't pick an update up: no button.
           td: +versionWithUpdate(a.version, updates.latest.agent, a.update_to, `/admin/agents/${a.id}/update`, list.pageUrl(), !a.revoked_at)
           td= fmtDate(a.created_at)
           td= fmtDate(a.last_used_at, 'never')
           td= a.revoked_at ? 'revoked' : 'active'
           td
-            .d-flex.justify-content-end
-              button.btn.btn-sm.btn-outline-secondary(
-                type="button"
-                data-bs-toggle="modal"
-                data-bs-target=`#editAgentModal-${a.id}`
-                aria-label=`Edit agent ${a.name}`
-              ) Edit
+            .d-flex.justify-content-end.text-nowrap
+              form(
+                method="post"
+                action=`/admin/agents/${a.id}/token`
+                data-confirm=a.revoked_at ? `Issue a new token for "${a.name}"? It becomes active again with it.` : `Issue a new token for "${a.name}"? Its current token stops working at once — update it wherever it's used (a CI secret).`
+                data-confirm-title="Issue a new token?"
+                data-confirm-ok="Issue token"
+                data-confirm-tone="primary"
+              )
+                input(type="hidden" name="returnTo" value=list.pageUrl())
+                button.btn.btn-sm.btn-outline-primary(type="submit" aria-label=`New token for ${a.name}` data-bs-toggle="tooltip" data-bs-title="Issue a new token (the old one stops working; shown once)")
+                  i.bi.bi-key
               if !a.revoked_at
                 form.ms-1(
                   method="post"
@@ -59,7 +76,18 @@ block content
                   data-confirm-ok="Revoke"
                 )
                   input(type="hidden" name="returnTo" value=list.pageUrl())
-                  button.btn.btn-sm.btn-outline-danger(type="submit") Revoke
+                  button.btn.btn-sm.btn-outline-warning(type="submit" aria-label=`Revoke ${a.name}` data-bs-toggle="tooltip" data-bs-title="Revoke the token (a new one can be issued later)")
+                    i.bi.bi-key-fill
+              form.ms-1(
+                method="post"
+                action=`/admin/agents/${a.id}/delete`
+                data-confirm=`Delete CI token "${a.name}"? Its token stops working and it leaves this list for good; its jobs stay, listed under its name.`
+                data-confirm-title="Delete CI token?"
+                data-confirm-ok="Delete"
+              )
+                input(type="hidden" name="returnTo" value=list.pageUrl())
+                button.btn.btn-sm.btn-outline-danger(type="submit" aria-label=`Delete ${a.name}` data-bs-toggle="tooltip" data-bs-title="Delete the CI token")
+                  i.bi.bi-trash
 
             .modal(tabindex="-1" id=`editAgentModal-${a.id}` aria-labelledby=`editAgentTitle-${a.id}`)
               .modal-dialog
@@ -73,12 +101,14 @@ block content
                       label.form-label(for=`agentName-${a.id}`) Name
                       input.form-control(id=`agentName-${a.id}` type="text" name="name" value=a.name required maxlength="100")
                       .form-text Only a label — the agent's token, and everything using it, keep working.
+                      label.form-label.mt-3(for=`agentGroup-${a.id}`) Group
+                      +groupSelect(`agentGroup-${a.id}`, a.group_id, groups)
                     .modal-footer
                       button.btn.btn-secondary(type="button" data-bs-dismiss="modal") Cancel
                       button.btn.btn-primary(type="submit") Save
       else
         tr
-          td.text-body-secondary(colspan="7")
+          td.text-body-secondary(colspan="8")
             if q
               | No agent matches “#{q}”. 
               a(href=list.urlFor({ q: '' })) Show all agents
@@ -96,6 +126,9 @@ block content
             .mb-3
               label.form-label Name
               input.form-control(type="text" name="name" placeholder="ci-firmware" required)
+            .mb-3
+              label.form-label(for="newAgentGroup") Group
+              +groupSelect('newAgentGroup', null, groups)
             .mb-3
               p.small.text-body-secondary.mb-0.
                 For a pipeline: its jobs get A- ids and it can read every job. People use their own access key

package/views/admin/users.pug

@@ -1,5 +1,6 @@
 extends ../layout
 include ../mixins/list-controls
+include ../mixins/group-select
 
 //- Users (§10.3). Roles: user — the Agent only; maintainer — the dashboard
 //- without its security features; admin — everything. A maintainer sees and
@@ -63,6 +64,7 @@ block content
       tr
         +sortHeader(list, 'username', 'User')
         +sortHeader(list, 'role', 'Role')
+        +sortHeader(list, 'group', 'Group')
         +sortHeader(list, 'status', 'Status')
         +sortHeader(list, 'used', 'Access key', 'desc')
         th.text-end
@@ -75,6 +77,11 @@ block content
             a.fw-medium(href=`#editUser-${u.id}` data-bs-toggle="modal" role="button")= userDisplayName(u)
           td
             span.badge(class=`text-bg-${roleTone[u.role]}` data-bs-toggle="tooltip" data-bs-title=roleHelp[u.role])= roleLabel(u.role)
+          td
+            if u.groupId && groupsById[u.groupId]
+              span.badge.text-bg-info= groupsById[u.groupId].name
+            else
+              span.text-body-secondary.small any
           td
             if u.blocked
               span.badge.text-bg-danger(data-bs-toggle="tooltip" data-bs-title=`Since ${fmtDate(u.blockedAt)}`) blocked
@@ -188,12 +195,15 @@ block content
                             .form-text Only an admin can change a role.
                           if !u.canUseDashboard && roles.length > 1
                             .form-text Making them a maintainer or admin gives them a temporary password for the dashboard.
+                        .col-12
+                          label.form-label(for=`u-${u.id}-group`) Group
+                          +groupSelect(`u-${u.id}-group`, u.groupId, groups)
                     .modal-footer
                       button.btn.btn-secondary(type="button" data-bs-dismiss="modal") Cancel
                       button.btn.btn-primary(type="submit") Save
       else
         tr
-          td.text-body-secondary(colspan="5")= q || roleFilter ? 'No user matches.' : 'No users yet.'
+          td.text-body-secondary(colspan="6")= q || roleFilter ? 'No user matches.' : 'No users yet.'
 
   //- The audit log: who did what to which account (web/routes.js auditRows).
   h2.h6.mt-4 Recent activity
@@ -202,13 +212,13 @@ block content
       table.table.table-sm.small.align-middle
         thead
           tr
-            th.text-nowrap Timestamp
+            th Timestamp
             th User
             th Action
         tbody
           each e in audit
             tr
-              td.text-nowrap.text-body-secondary= fmtDate(e.ts)
+              td.text-body-secondary= fmtDate(e.ts)
               td.text-nowrap= e.by
               td= e.action
   else
@@ -238,6 +248,9 @@ block content
               .col-12
                 label.form-label(for="new-role") Role
                 +roleSelect('new-role', 'user')
+              .col-12
+                label.form-label(for="new-group") Group
+                +groupSelect('new-group', null, groups)
               .col-12
                 .form-check.mt-1
                   input.form-check-input#new-key(type="checkbox" name="issueKey" value="1" checked)

package/views/groups/list.pug

@@ -8,12 +8,12 @@ block content
       button.btn.btn-primary.btn-sm(type="button" data-bs-toggle="modal" data-bs-target="#addGroupModal") Add group
 
   p.text-body-secondary.small: i.
-    A job can be constrained to run only on resources in a group with `thub run --group <id>` (§13.1).
-    Which groups a Client is in is set on its resource card (Groups tab, admins), or as `groups` in the Client's own config — the tab writes it there.
+    Give an agent a group — a user on #[a(href="/admin/users") Users], a CI token on #[a(href="/admin/agents") CI tokens] —
+    and its jobs run only on resources in that group (§13.1). Which groups a Client is in is set on its resource card (Groups tab).
 
   if totalCount
     .d-flex.flex-wrap.align-items-center.gap-2.mb-2
-      +searchForm(q, 'Search groups: name, id, comment', '/groups')
+      +searchForm(q, 'Search groups: name, comment', '/groups')
       if q
         span.small.text-body-secondary
           | #{groups.length} of #{totalCount} groups
@@ -24,9 +24,9 @@ block content
       thead
         tr
           th Name
-          th ID
           th Comment
           th Resources
+          th Agents
           th Created
           if canManage
             th Actions
@@ -34,18 +34,9 @@ block content
         each g in groups
           tr
             td= g.name
-            td
-              code.small.me-1= g.id
-              button.btn.btn-sm.btn-outline-secondary.copy-btn(
-                type="button"
-                aria-label="Copy group ID to clipboard"
-                data-bs-toggle="tooltip"
-                data-bs-title="Copy to clipboard"
-                data-copy=g.id
-              )
-                i.bi.bi-clipboard
             td= g.comment || '—'
             td= g.resourceCount
+            td(data-bs-toggle=g.agentNames.length ? 'tooltip' : null data-bs-title=g.agentNames.join(', ') || null)= g.agentNames.length
             td= fmtDate(g.created_at)
             if canManage
               td
@@ -53,7 +44,7 @@ block content
                 form.d-inline.ms-1(
                   method="post"
                   action=`/groups/${g.id}/delete`
-                  data-confirm=`Delete group "${g.name}"? Resources listing it just stop matching on it, and jobs targeting it (--group) can no longer be scheduled.`
+                  data-confirm=`Delete group "${g.name}"? Resources listing it just stop matching on it, and its agents go back to running their jobs on any resource.`
                   data-confirm-title="Delete group?"
                   data-confirm-ok="Delete group"
                 )
@@ -73,17 +64,6 @@ block content
                         .mb-3
                           label.form-label Comment
                           textarea.form-control(name="comment" rows="2")= g.comment || ''
-                        p.text-body-secondary.small.mb-0
-                          | ID:
-                          code.me-1= g.id
-                          button.btn.btn-sm.btn-outline-secondary.copy-btn(
-                            type="button"
-                            aria-label="Copy group ID to clipboard"
-                            data-bs-toggle="tooltip"
-                            data-bs-title="Copy to clipboard"
-                            data-copy=g.id
-                          )
-                            i.bi.bi-clipboard
                       .modal-footer
                         button.btn.btn-primary(type="submit") Save
   else if q
@@ -108,6 +88,5 @@ block content
               .mb-3
                 label.form-label Comment
                 textarea.form-control(name="comment" rows="2" placeholder="Optional")
-              p.text-body-secondary.small.mb-0 The group's id (a UUID) is generated once it's created.
             .modal-footer
               button.btn.btn-primary(type="submit") Create

package/views/help/_agent-cli.pug

@@ -21,7 +21,6 @@
         ['--type hw|sw', 'Required. Resource type.', '--type hw'],
         ['--board <name>', 'Shorthand for --label board:<name>.', '--board nucleo-f401re'],
         ['--label <l>', 'Required label (repeatable). The Client must have all of them.', '--label uart --label stlink'],
-        ['--group <id>', 'Only Clients in this group. Default: THUB_GROUP / config.', '--group 548ae4ae-…'],
         ['--client <name|id>', 'Only this Client; waits for it even if others are idle.', '--client lab-hw-01']
       ] },
       { title: 'What to run', rows: [

package/views/help/_agent-setup.pug

@@ -43,9 +43,9 @@
     thub config set url   #{coordinatorUrl}
     thub config set key   thk_…
     thub config set user  "Your Name"      # optional: job owner label
-    thub config set group <groupId>       # optional: default --group
   p.small.
-    These are saved in #[code ~/.config/thub/agent.json]. Order of precedence: flags (#[code --url], #[code --key]) →
+    These are saved in #[code ~/.config/thub/agent.json]. Which resource group your jobs run in isn't an Agent
+    setting: an admin or maintainer sets it for your user on the dashboard (#[code thub whoami] shows it). Order of precedence: flags (#[code --url], #[code --key]) →
     environment → config file.
   table.table.table-sm.small
     thead
@@ -59,9 +59,6 @@
       tr
         td: code THUB_KEY
         td Your access key, or a CI token in a pipeline. Keep it in your CI's secret store. (#[code THUB_TOKEN], #[code --token] and a saved #[code token] still work: the old names.)
-      tr
-        td: code THUB_GROUP
-        td Default #[code --group]
       tr
         td: code THUB_USER
         td Default #[code --user]

package/views/help/_client-setup.pug

@@ -38,7 +38,6 @@
           "name": "lab-hw-01",
           "type": "hw",
           "labels": ["board:nucleo-f401re", "uart", "stlink"],
-          "groups": ["<group id>"],
           "joinKey": "<the Coordinator's clientJoinKey>",
           "varDir": "/home/thub/var/lib/thub/client",
           "hw-devices": {
@@ -83,7 +82,7 @@
         tr
           td: code groups
           td No
-          td Group ids (from #[a(href="/groups") Groups]) this Client belongs to, for #[code thub run --group]. Admins can also set them on the resource card (Groups tab), which writes them here.
+          td The resource groups this Client belongs to. Set them on its resource card (Groups tab), which writes them here.
         tr
           td: code varDir
           td No

package/views/help/_coordinator.pug

@@ -121,7 +121,7 @@
     thub-admin user list | block | unblock | role | password | key | delete …
     thub-admin join-key generate                            # → clientJoinKey here, joinKey on every Client
     thub-admin agent add ci-firmware                        # CI token for a pipeline: job ids A-00001…
-    thub-admin group add ci-nightly --comment "nightly pool" # → a group id for thub run --group
+    thub-admin group add ci-nightly --comment "nightly pool" # then give it to users / CI tokens on the dashboard
     thub-admin resource maintenance <resourceId> --on
     thub-admin jobs reset --yes                             # cancel every active job
     thub-admin jobs clean --yes --before "01/09/2026 00:00:00"

package/views/help/_env.pug

@@ -37,7 +37,7 @@
       ['JOB_TYPE', '--type', 'hw or sw'],
       ['JOB_BOARD', '--board', 'the board name'],
       ['JOB_LABEL / JOB_LABEL_<n>', '--board, --label', 'all labels, comma-separated / each'],
-      ['JOB_GROUP', '--group', 'the group id'],
+      ['JOB_GROUP', '(dashboard)', 'the submitting agent\'s group, if it has one'],
       ['JOB_CLIENT', '--client', 'this Client\'s name'],
       ['JOB_USER', '--user', 'as given'],
       ['JOB_COMMAND', '--command', 'the command itself'],

package/views/help/_troubleshooting.pug

@@ -6,7 +6,7 @@
       ['A Client doesn\'t appear on Resources', 'Check `journalctl -u thub-client@<instance> -f`. A `503` at registration means the Coordinator has no `clientJoinKey`; a `401` means the `joinKey` differs. Also check that `coordinatorUrl` is reachable from the lab (`curl -sI <url>/login`).'],
       ['A Client flaps or two machines show as one resource', 'Both use the same `.client-id` (a cloned VM or a shared config file). Delete `<varDir>/<instance>/.client-id` on one of them and restart it, or set a distinct `clientId`.'],
       ['Name already in use (`409`)', 'Another live Client holds that name. Rename one of them in its config or from the resource card. A name held by an `OUT_OF_SERVICE` resource is reclaimed automatically.'],
-      ['The job is rejected with `422`', 'No registered Client can ever match its type, labels, group or client. Compare `thub resources` with your `--type`, `--board`/`--label` and `--group`.'],
+      ['The job is rejected with `422`', 'No registered Client can ever match its type, labels, group or client. Compare `thub resources` with your `--type` and `--board`/`--label`; your group (set on the dashboard, see `thub whoami`) must have a Client of that kind.'],
       ['The job stays `QUEUED`', 'Matching Clients are all `BUSY`, locked (`local`), in `MAINTENANCE` or offline, or the job is pinned with `--client`. It times out after `--timeout`.'],
       ['`ERROR` during prepare', 'The clone, download or DUT image pull failed; the job log names the reason. For git, check the Client user\'s keys and `known_hosts` (`ssh -T git@<host>` as that user). For images, check the Client user\'s `docker login`.'],
       ['Permission denied on `/dev/ttyUSB*` or `docker.sock`', 'Docker or the device groups were added after the Client was installed. Re-run `sudo npm i -g @andrian.yablonskyy/thub-client` so the unit gets the `dialout`/`plugdev`/`docker` groups, then restart.'],

package/views/jobs/show.pug

@@ -33,6 +33,10 @@ block content
     dd.col-sm-10= job.resource ? job.resource.name : job.resource_name ? `${job.resource_name} (removed)` : '—'
     dt.col-sm-2 Target
     dd.col-sm-10= `${job.spec.target.type} — ${(job.spec.target.labels || []).join(', ')}`
+    if job.spec.target.group
+      //- The submitting agent's group (set on the dashboard), by name.
+      dt.col-sm-2 Group
+      dd.col-sm-10= targetGroup ? targetGroup.name : '(a deleted group)'
     if job.spec.target.client
       dt.col-sm-2 Client
       dd.col-sm-10= pinnedClient ? pinnedClient.name : job.spec.target.client

package/views/mixins/client-config.pug

@@ -145,16 +145,11 @@ mixin groupsPane(r, returnTo, groupsById)
                   span.fw-medium= g.name
                   if g.comment
                     span.small.text-body-secondary= ` — ${g.comment}`
-                  br
-                  code.small.text-body-secondary= g.id
             each id in unknown
               label.list-group-item.d-flex.gap-2.align-items-start
                 input.form-check-input.flex-shrink-0.mt-1(type="checkbox" name="groups" value=id checked)
-                span
-                  span.text-body-secondary (deleted group)
-                  br
-                  code.small.text-body-secondary= id
-          .form-text A job run with #[code thub run --group <id>] is scheduled only on Clients in that group; one that asks for no group can run on any Client.
+                span.text-body-secondary (a deleted group)
+          .form-text An agent given a group (on Users or CI tokens) runs its jobs only on Clients in it; an agent without one, on any Client.
           if canEdit && r.config_support === 'file'
             .d-flex.justify-content-end.mt-3
               button.btn.btn-sm.btn-primary(type="submit" data-bs-toggle="tooltip" data-bs-title="Save the groups — in effect at once; the Client writes them to its config file") Save groups

package/views/mixins/group-select.pug

@@ -0,0 +1,9 @@
+//- The resource group an agent's jobs run in (§13.1) — a user's on Users, a
+//- CI token's on CI tokens. Only here, on the dashboard: `thub run` has no
+//- --group. Groups by name; none = any resource.
+mixin groupSelect(id, selected, groups)
+  select.form-select(id=id name="groupId")
+    option(value="" selected=!selected) Any resource (no group)
+    each g in groups
+      option(value=g.id selected=g.id === selected)= g.name
+  .form-text Its jobs run only on resources in this group. Manage groups on #[a(href="/groups") Groups].

package/views/resources/list.pug

@@ -45,7 +45,7 @@ block content
           td
             if r.group_ids.length
               each gid in r.group_ids
-                span.badge.text-bg-info.me-1(data-bs-toggle="tooltip" data-bs-title=gid)= groupsById[gid] ? groupsById[gid].name : `(unknown: ${gid})`
+                span.badge.text-bg-info.me-1= groupsById[gid] ? groupsById[gid].name : '(deleted group)'
             else
               span.text-body-secondary —
           td= r.busy_source ? `${r.busy_source}${r.busy_reason ? ' — ' + r.busy_reason : ''}` : '—'