@andrian.yablonskyy/thub-coordinator 1.0.18 → 1.0.19

package/package.json

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

package/src/db/migrations/016_add_list_prefs.sql

@@ -0,0 +1,5 @@
+-- Per-user list view preferences (README §10.1): page size and sort
+-- column/direction for each dashboard list, as JSON keyed by page —
+-- {"jobs": {"size": 25, "sort": "created", "dir": "desc"}, "resources": {...}}.
+-- NULL/missing keys fall back to each page's defaults (services/list-prefs.js).
+ALTER TABLE admin_users ADD COLUMN list_prefs TEXT;

package/src/services/admin-users.js

@@ -14,7 +14,8 @@
 'use strict';
 
 const crypto = require('node:crypto'),
-  { v4: uuid } = require('uuid');
+  { v4: uuid } = require('uuid'),
+  { normalize: normalizeListPrefs } = require('./list-prefs');
 
 function hashPassword(password){
   const salt = crypto.randomBytes(16).toString('hex'),
@@ -44,10 +45,21 @@ function toProfile(row){
     avatarPath: row.avatar_path,
     timezone: row.timezone,
     theme: row.theme,
-    sessionTimeoutMin: row.session_timeout_min
+    sessionTimeoutMin: row.session_timeout_min,
+    listPrefs: parseListPrefs(row.list_prefs)
   };
 }
 
+function parseListPrefs(json){
+  try {
+    const prefs = JSON.parse(json || '{}');
+    return prefs && typeof prefs === 'object' && !Array.isArray(prefs) ? prefs : {};
+  }
+  catch {
+    return {};
+  }
+}
+
 // §10: dashboard login uses its own admin/viewer account table with
 // session cookies — deliberately separate from the API bearer tokens.
 function createAdminUsersService(db){
@@ -157,6 +169,18 @@ function createAdminUsersService(db){
     return getById(id);
   }
 
+  // Remembers one list page's view (size/sort/dir, §10.1) for this user;
+  // stored normalized, so only valid values ever reach the profile.
+  function setListPrefs(id, list, prefs){
+    const row = db.prepare('SELECT list_prefs FROM admin_users WHERE id = ?').get(id);
+    if (!row){
+      throw Object.assign(new Error('Unknown user'), { status: 404 });
+    }
+    const all = { ...parseListPrefs(row.list_prefs), [list]: normalizeListPrefs(list, prefs) };
+    db.prepare('UPDATE admin_users SET list_prefs = ? WHERE id = ?').run(JSON.stringify(all), id);
+    return getById(id);
+  }
+
   return {
     getByUsername,
     getById,
@@ -166,6 +190,7 @@ function createAdminUsersService(db){
     changePassword,
     verify,
     updateProfile,
+    setListPrefs,
     SESSION_TIMEOUT_OPTIONS_MIN,
     THEMES
   };

package/src/services/jobs.js

@@ -13,7 +13,8 @@
 
 'use strict';
 
-const { validateJobSpec, JOB_STATES, ACTIVE_JOB_STATES, TERMINAL_JOB_STATES } = require('@andrian.yablonskyy/thub-common');
+const { validateJobSpec, JOB_STATES, ACTIVE_JOB_STATES, TERMINAL_JOB_STATES } = require('@andrian.yablonskyy/thub-common'),
+  { paginate } = require('./list-prefs');
 
 function rowToJob(row){
   if (!row){
@@ -79,6 +80,44 @@ function createJobsService(db, { bus, events, registry, artifacts, config }){
     return db.prepare(sql).all(...params).map(rowToJob);
   }
 
+  // Dashboard /jobs (§10): one sorted page plus the total, both in SQL so a
+  // long history never has to be loaded whole. `sort` is a list-prefs key.
+  const PAGE_SORT_SQL = {
+    id: 'jobs.id',
+    source: 'jobs.source',
+    user: 'json_extract(jobs.spec, \'$.user\')',
+    state: 'jobs.state',
+    resource: 'COALESCE(r.name, jobs.resource_name)',
+    created: 'jobs.created_at',
+    duration: 'jobs.duration_sec'
+  };
+
+  function page({ state, source, sort = 'created', dir = 'desc', size = 25, page: pageNo = 1 } = {}){
+    const where = [],
+      params = [];
+    if (state){
+      where.push('jobs.state = ?');
+      params.push(state);
+    }
+    if (source){
+      where.push('jobs.source = ?');
+      params.push(source);
+    }
+    const whereSql = where.length ? `WHERE ${where.join(' AND ')}` : '',
+      column = PAGE_SORT_SQL[sort] || PAGE_SORT_SQL.created,
+      order = dir === 'asc' ? 'ASC' : 'DESC',
+      total = db.prepare(`SELECT COUNT(*) AS n FROM jobs ${whereSql}`).get(...params).n,
+      pagination = paginate(total, size, pageNo),
+      // Empty values (no user, never ran, …) last either way; created_at
+      // breaks ties so paging is stable.
+      rows = db.prepare(
+        `SELECT jobs.* FROM jobs LEFT JOIN resources r ON r.id = jobs.resource_id ${whereSql}
+         ORDER BY ${column} IS NULL, ${column} ${order}, jobs.created_at DESC
+         LIMIT ? OFFSET ?`
+      ).all(...params, pagination.limit, pagination.offset);
+    return { rows: rows.map(rowToJob), pagination };
+  }
+
   function countQueuedForAgent(agentId){
     return db
       .prepare('SELECT COUNT(*) AS n FROM jobs WHERE agent_id = ? AND state IN (\'QUEUED\',\'ASSIGNED\')')
@@ -363,6 +402,15 @@ function createJobsService(db, { bus, events, registry, artifacts, config }){
     return active.length;
   }
 
+  // How many jobs Reset queue / Clean history would touch — shown in their
+  // confirmation modals on /jobs.
+  function countActiveAndFinished(){
+    const count = (states) => db
+      .prepare(`SELECT COUNT(*) AS n FROM jobs WHERE state IN (${[...states].map(() => '?').join(',')})`)
+      .get(...states).n;
+    return { active: count(ACTIVE_JOB_STATES), finished: count(TERMINAL_JOB_STATES) };
+  }
+
   // Admin: "clean the queue" — permanently delete finished jobs (and their
   // logs/artifacts, on disk and in the DB), for when the history itself,
   // not just active work, needs clearing out. Unlike the nightly retention
@@ -406,6 +454,7 @@ function createJobsService(db, { bus, events, registry, artifacts, config }){
   return {
     get,
     list,
+    page,
     create,
     setState,
     cancel,
@@ -420,6 +469,7 @@ function createJobsService(db, { bus, events, registry, artifacts, config }){
     checkAssignAcks,
     reconcileOnStartup,
     resetQueue,
+    countActiveAndFinished,
     cleanHistory
   };
 }

package/src/services/list-prefs.js

@@ -0,0 +1,92 @@
+/**
+ * @file        packages/coordinator/src/services/list-prefs.js
+ * @description Per-user list view preferences (page size, sort column/direction) for the dashboard's
+ *              Jobs and Resources pages (README §10.1), plus the pagination math they share
+ *
+ * @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';
+
+// 'all' shows every record on one page.
+const PAGE_SIZES = [10, 25, 50, 100, 'all'],
+  DEFAULT_PAGE_SIZE = 25,
+  DIRS = ['asc', 'desc'],
+
+  // Sortable columns per page, and each page's default order. The keys are
+  // what the URL (?sort=) and the stored profile carry; the pages map them
+  // to actual columns (jobs.page's SQL, the resources route's comparators).
+  LISTS = {
+    jobs: {
+      sorts: ['id', 'source', 'user', 'state', 'resource', 'created', 'duration'],
+      defaults: { size: DEFAULT_PAGE_SIZE, sort: 'created', dir: 'desc' }
+    },
+    resources: {
+      sorts: ['name', 'type', 'version', 'status', 'heartbeat'],
+      defaults: { size: DEFAULT_PAGE_SIZE, sort: 'name', dir: 'asc' }
+    }
+  };
+
+function parseSize(value){
+  if (value === 'all'){
+    return 'all';
+  }
+  const n = Number(value);
+  return PAGE_SIZES.includes(n) ? n : undefined;
+}
+
+// A complete, valid {size, sort, dir} for `list`: each field from `prefs`
+// when valid there, else that page's default.
+function normalize(list, prefs = {}){
+  const def = LISTS[list];
+  if (!def){
+    throw Object.assign(new Error(`Unknown list "${list}"`), { status: 400 });
+  }
+  return {
+    size: parseSize(prefs.size) ?? def.defaults.size,
+    sort: def.sorts.includes(prefs.sort) ? prefs.sort : def.defaults.sort,
+    dir: DIRS.includes(prefs.dir) ? prefs.dir : def.defaults.dir
+  };
+}
+
+// What a request asks for: the stored prefs, overridden by whichever of
+// ?size / ?sort / ?dir the URL carries (invalid values are ignored).
+function fromQuery(list, query, stored){
+  const base = normalize(list, stored),
+    wanted = { ...base };
+  if (query.size !== undefined && parseSize(query.size) !== undefined){
+    wanted.size = parseSize(query.size);
+  }
+  if (LISTS[list].sorts.includes(query.sort)){
+    wanted.sort = query.sort;
+  }
+  if (DIRS.includes(query.dir)){
+    wanted.dir = query.dir;
+  }
+  return { prefs: wanted, changed: ['size', 'sort', 'dir'].some((k) => wanted[k] !== base[k]) };
+}
+
+// Page window for `total` records: `page` is 1-based and clamped into range.
+function paginate(total, size, page){
+  const limit = size === 'all' ? Math.max(total, 1) : size,
+    pages = Math.max(1, Math.ceil(total / limit)),
+    current = Math.min(Math.max(1, Number.parseInt(page, 10) || 1), pages),
+    offset = (current - 1) * limit;
+  return {
+    page: current,
+    pages,
+    total,
+    offset,
+    limit,
+    from: total ? offset + 1 : 0,
+    to: Math.min(offset + limit, total)
+  };
+}
+
+module.exports = { PAGE_SIZES, DEFAULT_PAGE_SIZE, LISTS, normalize, fromQuery, paginate };

package/src/web/routes.js

@@ -20,12 +20,25 @@ const fs = require('node:fs'),
   multer = require('multer'),
   { requireAdminSession, requireAdminRole } = require('../auth'),
   { attachJobStream } = require('../api/sse'),
-  { RESOURCE_STATES, JOB_STATES, ACTIVE_JOB_STATES, isNewer } = require('@andrian.yablonskyy/thub-common');
+  { RESOURCE_STATES, JOB_STATES, ACTIVE_JOB_STATES, isNewer, compareVersions } = require('@andrian.yablonskyy/thub-common'),
+  listPrefs = require('../services/list-prefs');
+
+// Resources page sort keys (list-prefs.js) -> comparators. Empty values
+// (never heartbeated, no version reported) sort last in both directions.
+const RESOURCE_SORT_VALUE = {
+    name: (r) => r.name,
+    type: (r) => r.type,
+    version: (r) => r.client_version,
+    status: (r) => r.status,
+    heartbeat: (r) => r.last_heartbeat_at
+  },
+  compareResourceValues = (sort, a, b) =>
+    sort === 'version' ? compareVersions(a, b) : String(a).localeCompare(String(b), undefined, { numeric: true }),
 
-// §10.1: avatar uploads are small, single images — a hard size cap and an
-// allow-list of image mimetypes, same spirit as the join-key/token checks
-// elsewhere (reject outright rather than trying to sanitize).
-const AVATAR_MAX_BYTES = 2 * 1024 * 1024,
+  // §10.1: avatar uploads are small, single images — a hard size cap and an
+  // allow-list of image mimetypes, same spirit as the join-key/token checks
+  // elsewhere (reject outright rather than trying to sanitize).
+  AVATAR_MAX_BYTES = 2 * 1024 * 1024,
   AVATAR_EXT_BY_MIMETYPE = {
     'image/png': 'png',
     'image/jpeg': 'jpg',
@@ -55,6 +68,30 @@ function createWebRouter({ services, config }){
     return typeof target === 'string' && /^\/(?![\/\\])/.test(target) ? target : fallback;
   }
 
+  // A list page's view (§10.1): the user's stored size/sort/dir, overridden
+  // by ?size/?sort/?dir — and a change is saved straight to their profile,
+  // so it's what they get next time on any device. ?page isn't saved.
+  function listView(req, res, list, extraQuery = {}){
+    const user = req.session.user,
+      { prefs, changed } = listPrefs.fromQuery(list, req.query, user.listPrefs?.[list]);
+    if (changed){
+      req.session.user = services.adminUsers.setListPrefs(user.id, list, prefs);
+      res.locals.user = req.session.user;
+    }
+    const base = { ...extraQuery, size: prefs.size, sort: prefs.sort, dir: prefs.dir },
+      // Link to this list with some params changed; changing size or sort
+      // restarts at page 1. Empty params are dropped.
+      urlFor = (changes = {}) => {
+        const q = { ...base, ...changes };
+        if (('size' in changes || 'sort' in changes) && !('page' in changes)){
+          delete q.page;
+        }
+        const qs = new URLSearchParams(Object.entries(q).filter(([, v]) => v !== undefined && v !== null && v !== '')).toString();
+        return `${req.baseUrl}${req.path}${qs ? `?${qs}` : ''}`;
+      };
+    return { prefs, urlFor, pageSizes: listPrefs.PAGE_SIZES };
+  }
+
   // The job each resource is on (if any), for the resource card's Cancel.
   function withActiveJobs(resources){
     return resources.map((r) => ({ ...r, activeJob: services.jobs.activeForResource(r.id) }));
@@ -231,12 +268,26 @@ function createWebRouter({ services, config }){
   });
 
   router.get('/resources', (req, res) => {
-    const groupsById = Object.fromEntries(services.groups.list().map((g) => [g.id, g]));
+    const groupsById = Object.fromEntries(services.groups.list().map((g) => [g.id, g])),
+      view = listView(req, res, 'resources'),
+      { sort, dir, size } = view.prefs,
+      value = RESOURCE_SORT_VALUE[sort],
+      sorted = services.registry.list().sort((a, b) => {
+        const va = value(a),
+          vb = value(b);
+        if (va == null || vb == null){
+          return (va == null) - (vb == null);
+        }
+        return (dir === 'asc' ? 1 : -1) * compareResourceValues(sort, va, vb) || a.name.localeCompare(b.name);
+      }),
+      pagination = listPrefs.paginate(sorted.length, size, req.query.page),
+      pageUrl = (changes) => view.urlFor({ page: pagination.page, ...changes });
     res.render('resources/list', {
       title: 'Resources',
       active: 'resources',
-      resources: withActiveJobs(services.registry.list()),
-      groupsById
+      resources: withActiveJobs(sorted.slice(pagination.offset, pagination.offset + pagination.limit)),
+      groupsById,
+      list: { ...view, pagination, pageUrl }
     });
   });
 
@@ -413,22 +464,25 @@ function createWebRouter({ services, config }){
 
   router.get('/jobs', (req, res) => {
     const filters = { state: req.query.state || undefined, source: req.query.source || undefined },
-      jobs = services.jobs.list({ ...filters, limit: 200 }).map((j) => ({
+      view = listView(req, res, 'jobs', filters),
+      { rows, pagination } = services.jobs.page({ ...filters, ...view.prefs, page: req.query.page }),
+      jobs = rows.map((j) => ({
         ...j,
         resource: j.resource_id ? services.registry.get(j.resource_id) : null,
         active: ACTIVE_JOB_STATES.has(j.state)
-      }));
+      })),
+      pageUrl = (changes) => view.urlFor({ page: pagination.page, ...changes });
     res.render('jobs/list', {
       title: 'Jobs',
       active: 'jobs',
       jobs,
       filters,
-      // Keeps the list's filters across a row's Cancel.
-      filterQuery: (() => {
-        const q = new URLSearchParams(Object.entries(filters).filter(([, v]) => v)).toString();
-        return q ? `?${q}` : '';
-      })(),
-      canManage: req.session.user.role === 'admin'
+      list: { ...view, pagination, pageUrl },
+      // A row's Cancel comes back to this exact view (filters, sort, page).
+      returnTo: pageUrl(),
+      canManage: req.session.user.role === 'admin',
+      // For the Reset queue / Clean history confirmation modals.
+      jobCounts: req.session.user.role === 'admin' ? services.jobs.countActiveAndFinished() : null
     });
   });
 

package/test/list-prefs.test.js

@@ -0,0 +1,89 @@
+/**
+ * @file        packages/coordinator/test/list-prefs.test.js
+ * @description Tests: list view preferences (page size/sort), their storage in the user profile, and paged job queries
+ *
+ * @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'),
+  { EventEmitter } = require('node:events'),
+  { openDb } = require('../src/db'),
+  { createAdminUsersService } = require('../src/services/admin-users'),
+  { createEventsService } = require('../src/services/events'),
+  { createRegistryService } = require('../src/services/registry'),
+  { createAgentsService } = require('../src/services/agents'),
+  { createJobsService } = require('../src/services/jobs'),
+  { normalize, fromQuery, paginate } = require('../src/services/list-prefs');
+
+test('normalize fills defaults and drops invalid values', () => {
+  assert.deepEqual(normalize('jobs'), { size: 25, sort: 'created', dir: 'desc' });
+  assert.deepEqual(normalize('resources', { size: '100', sort: 'status', dir: 'desc' }), { size: 100, sort: 'status', dir: 'desc' });
+  assert.deepEqual(normalize('resources', { size: 7, sort: 'labels', dir: 'up' }), { size: 25, sort: 'name', dir: 'asc' });
+  assert.equal(normalize('jobs', { size: 'all' }).size, 'all');
+  assert.throws(() => normalize('nope'), /Unknown list/);
+});
+
+test('fromQuery overrides stored prefs and reports whether anything changed', () => {
+  const stored = { size: 50, sort: 'state', dir: 'asc' };
+  assert.deepEqual(fromQuery('jobs', {}, stored), { prefs: stored, changed: false });
+  assert.deepEqual(fromQuery('jobs', { size: '10', page: '3' }, stored), { prefs: { ...stored, size: 10 }, changed: true });
+  assert.equal(fromQuery('jobs', { sort: 'bogus', size: '11' }, stored).changed, false); // invalid: ignored
+});
+
+test('paginate clamps the page and computes the window', () => {
+  assert.deepEqual(paginate(112, 25, '3'), { page: 3, pages: 5, total: 112, offset: 50, limit: 25, from: 51, to: 75 });
+  assert.equal(paginate(112, 25, '99').page, 5);
+  assert.equal(paginate(112, 25, 'x').page, 1);
+  assert.deepEqual(paginate(112, 'all', 1), { page: 1, pages: 1, total: 112, offset: 0, limit: 112, from: 1, to: 112 });
+  assert.deepEqual(paginate(0, 10, 1), { page: 1, pages: 1, total: 0, offset: 0, limit: 10, from: 0, to: 0 });
+});
+
+test('list prefs are stored per page in the user profile', () => {
+  const users = createAdminUsersService(openDb(':memory:')),
+    { id } = users.create({ username: 'alice', password: 'pw', role: 'admin' });
+  assert.deepEqual(users.getById(id).listPrefs, {});
+
+  users.setListPrefs(id, 'jobs', { size: 100, sort: 'duration', dir: 'asc' });
+  const profile = users.setListPrefs(id, 'resources', { size: 'all', sort: 'nonsense' });
+  assert.deepEqual(profile.listPrefs, {
+    jobs: { size: 100, sort: 'duration', dir: 'asc' },
+    resources: { size: 'all', sort: 'name', dir: 'asc' }
+  });
+});
+
+test('jobs.page sorts and pages in SQL, with empty values last', () => {
+  const db = openDb(':memory:'),
+    bus = new EventEmitter(),
+    events = createEventsService(db),
+    registry = createRegistryService(db, { bus, events }),
+    { agent } = createAgentsService(db, { events }).create({ name: 'ci', kind: 'ci' }),
+    config = { scheduler: { maxQueuedPerAgent: 100 }, jobs: { defaultTimeoutSec: 60, maxTimeoutSec: 60 } },
+    jobs = createJobsService(db, { bus, events, registry, artifacts: {}, config });
+  registry.registerAuto({ clientId: 'c', name: 'lab', type: 'sw', labels: [] });
+
+  const ids = ['carol', 'alice', null, 'bob'].map((user) =>
+      jobs.create({
+        agentId: agent.id,
+        source: 'cli',
+        spec: { target: { type: 'sw' }, firmware: { url: 'https://x/a' }, tests: { url: 'https://x/t' }, ...(user ? { user } : {}) }
+      }).id),
+
+    byUser = (dir) => jobs.page({ sort: 'user', dir, size: 'all' }).rows.map((j) => j.spec.user ?? null);
+  assert.deepEqual(byUser('asc'), ['alice', 'bob', 'carol', null]);
+  assert.deepEqual(byUser('desc'), ['carol', 'bob', 'alice', null]);
+
+  const second = jobs.page({ sort: 'id', dir: 'asc', size: 2, page: 2 });
+  assert.deepEqual(second.rows.map((j) => j.id), ids.slice(2));
+  assert.equal(second.pagination.total, 4);
+  assert.equal(second.pagination.pages, 2);
+  assert.equal(jobs.page({ state: 'PASSED' }).pagination.total, 0);
+});

package/views/jobs/list.pug

@@ -1,15 +1,15 @@
 extends ../layout
 include ../mixins/status-badge
+include ../mixins/list-controls
+include ../mixins/confirm-modal
 
 block content
   .d-flex.justify-content-between.align-items-center.mb-3
     h1.h4.mb-0 Jobs
     if canManage
       .btn-group
-        form(method="post" action="/jobs/reset-queue" onsubmit="return confirm('Cancel every queued/assigned/preparing/running job? This stops in-flight work.')")
-          button.btn.btn-sm.btn-outline-warning(type="submit") Reset queue
-        form.ms-1(method="post" action="/jobs/clean-history" onsubmit="return confirm('Permanently delete all finished jobs and their logs/artifacts? This cannot be undone.')")
-          button.btn.btn-sm.btn-outline-danger(type="submit") Clean history
+        button.btn.btn-sm.btn-outline-warning(type="button" data-bs-toggle="modal" data-bs-target="#reset-queue-modal") Reset queue
+        button.btn.btn-sm.btn-outline-danger.ms-1(type="button" data-bs-toggle="modal" data-bs-target="#clean-history-modal") Clean history
 
   form.row.g-2.mb-3(method="get")
     .col-auto
@@ -22,17 +22,21 @@ block content
         option(value="") any source
         option(value="ci" selected=filters.source === 'ci') ci
         option(value="cli" selected=filters.source === 'cli') cli
+    .col-auto.ms-auto
+      +pageSizePicker(list)
+
+  +listToolbar(list, 'jobs')
 
   table.table.table-hover.align-middle
     thead
       tr
-        th Job
-        th Source
-        th User
-        th State
-        th Resource
-        th Created
-        th Duration
+        +sortHeader(list, 'id', 'Job')
+        +sortHeader(list, 'source', 'Source')
+        +sortHeader(list, 'user', 'User')
+        +sortHeader(list, 'state', 'State')
+        +sortHeader(list, 'resource', 'Resource')
+        +sortHeader(list, 'created', 'Created', 'desc')
+        +sortHeader(list, 'duration', 'Duration', 'desc')
         if canManage
           th
     tbody
@@ -54,6 +58,52 @@ block content
                   data-confirm=`Cancel job ${j.id}?`
                   onsubmit="return confirm(this.dataset.confirm)"
                 )
-                  input(type="hidden" name="returnTo" value=`/jobs${filterQuery}`)
+                  input(type="hidden" name="returnTo" value=returnTo)
                   button.btn.btn-sm.btn-outline-danger(type="submit" aria-label="Cancel" title="Cancel this job")
                     i.bi.bi-x-circle
+
+  if canManage
+    +confirmModal({
+      id: 'reset-queue-modal',
+      tone: 'warning',
+      icon: 'bi-exclamation-triangle-fill',
+      title: 'Reset the job queue?',
+      action: '/jobs/reset-queue',
+      confirmLabel: 'Cancel all active jobs',
+      confirmIcon: 'bi-x-octagon',
+      disabled: !jobCounts.active
+    })
+      if jobCounts.active
+        p
+          | This cancels
+          |
+          strong= `${jobCounts.active} active job${jobCounts.active === 1 ? '' : 's'}`
+          |  — everything queued, assigned, preparing or running. Running jobs are stopped on their Clients, and all of them end as
+          |
+          code CANCELED
+          | .
+        p.small.text-body-secondary.mb-0 Finished jobs, logs and artifacts are not touched.
+      else
+        p.mb-0 There are no active jobs — nothing to cancel.
+
+    +confirmModal({
+      id: 'clean-history-modal',
+      tone: 'danger',
+      icon: 'bi-trash3-fill',
+      title: 'Clean job history?',
+      action: '/jobs/clean-history',
+      confirmLabel: 'Delete finished jobs',
+      confirmIcon: 'bi-trash3',
+      disabled: !jobCounts.finished
+    })
+      if jobCounts.finished
+        p
+          | This permanently deletes
+          |
+          strong= `${jobCounts.finished} finished job${jobCounts.finished === 1 ? '' : 's'}`
+          |  together with their logs and artifacts (database rows and files on disk).
+        p.mb-0
+          strong This cannot be undone.
+          |  Active jobs are not touched.
+      else
+        p.mb-0 There are no finished jobs — nothing to delete.

package/views/mixins/confirm-modal.pug

@@ -0,0 +1,26 @@
+//- A confirmation modal for a destructive admin action that POSTs to
+//- `opts.action`: opened by a button with data-bs-toggle="modal"
+//- data-bs-target="#<opts.id>" (no JS needed). The block is the body text.
+//- opts: id, title, action, confirmLabel, and optional tone (Bootstrap
+//- color, default danger), icon / confirmIcon (bootstrap-icons classes),
+//- disabled (nothing to do — the confirm button is disabled).
+mixin confirmModal(opts)
+  - const tone = opts.tone || 'danger'
+  .modal.fade(id=opts.id tabindex="-1" aria-labelledby=`${opts.id}-title` aria-hidden="true")
+    .modal-dialog.modal-dialog-centered
+      .modal-content
+        .modal-header(class=`text-bg-${tone}`)
+          h5.modal-title(id=`${opts.id}-title`)
+            if opts.icon
+              i.bi.me-2(class=opts.icon)
+            = opts.title
+          button.btn-close(type="button" data-bs-dismiss="modal" aria-label="Close")
+        .modal-body
+          block
+        .modal-footer
+          button.btn.btn-secondary(type="button" data-bs-dismiss="modal") Keep
+          form(method="post" action=opts.action)
+            button.btn(type="submit" class=`btn-${tone}` disabled=opts.disabled)
+              if opts.confirmIcon
+                i.bi.me-1(class=opts.confirmIcon)
+              = opts.confirmLabel

package/views/mixins/list-controls.pug

@@ -0,0 +1,61 @@
+//- Pagination and sorting for the dashboard's list pages (Jobs, Resources;
+//- README §10.1). `list` comes from routes.js listView(): prefs {size, sort,
+//- dir}, pagination {page, pages, total, from, to}, pageSizes, urlFor(changes)
+//- (link with params changed; size/sort changes restart at page 1).
+
+//- Records-per-page picker — placed on the right of the page's filter row.
+//- Navigates on change (no `name`), so it never rides along with a filter
+//- form it sits in.
+mixin pageSizePicker(list)
+  .d-flex.align-items-center.gap-2
+    label.small.text-body-secondary.mb-0.text-nowrap(for="list-page-size") Show
+    select.form-select.form-select-sm.w-auto#list-page-size(
+      aria-label="Records per page"
+      onchange="location.href = this.value"
+    )
+      each s in list.pageSizes
+        option(value=list.urlFor({ size: s }) selected=list.prefs.size === s)= s === 'all' ? 'All' : s
+
+//- Shown above the table: "Showing 26–50 of 312 jobs" and the page links.
+mixin listToolbar(list, noun)
+  - const p = list.pagination
+  .d-flex.flex-wrap.align-items-center.justify-content-between.gap-2.mb-2
+    span.small.text-body-secondary
+      if p.total
+        | Showing #{p.from}–#{p.to} of #{p.total} #{noun}
+      else
+        | No #{noun}
+    if p.pages > 1
+      +pager(list)
+
+//- First / previous / a window of pages around the current one / next / last.
+mixin pager(list)
+  - const p = list.pagination
+  - const from = Math.max(1, Math.min(p.page - 2, p.pages - 4))
+  - const to = Math.min(p.pages, from + 4)
+  nav(aria-label="Pages")
+    ul.pagination.pagination-sm.mb-0
+      li.page-item(class=p.page === 1 ? 'disabled' : null)
+        a.page-link(href=list.pageUrl({ page: 1 }) aria-label="First page") «
+      li.page-item(class=p.page === 1 ? 'disabled' : null)
+        a.page-link(href=list.pageUrl({ page: p.page - 1 }) aria-label="Previous page") ‹
+      - for (let n = from; n <= to; n++)
+        li.page-item(class=n === p.page ? 'active' : null aria-current=n === p.page ? 'page' : null)
+          a.page-link(href=list.pageUrl({ page: n }))= n
+      li.page-item(class=p.page === p.pages ? 'disabled' : null)
+        a.page-link(href=list.pageUrl({ page: p.page + 1 }) aria-label="Next page") ›
+      li.page-item(class=p.page === p.pages ? 'disabled' : null)
+        a.page-link(href=list.pageUrl({ page: p.pages }) aria-label="Last page") »
+
+//- A sortable column header: click to sort by it, again to flip direction.
+//- `firstDir` is the direction a column starts in (desc for times/durations).
+mixin sortHeader(list, key, label, firstDir)
+  - const active = list.prefs.sort === key
+  - const nextDir = active ? (list.prefs.dir === 'asc' ? 'desc' : 'asc') : (firstDir || 'asc')
+  th(aria-sort=active ? (list.prefs.dir === 'asc' ? 'ascending' : 'descending') : null)
+    a.link-body-emphasis.text-decoration-none.text-nowrap(href=list.urlFor({ sort: key, dir: nextDir }))
+      = label
+      if active
+        i.bi.ms-1(class=list.prefs.dir === 'asc' ? 'bi-caret-up-fill' : 'bi-caret-down-fill')
+      else
+        i.bi.bi-arrow-down-up.ms-1.text-body-tertiary.small

package/views/resources/list.pug

@@ -2,26 +2,31 @@ extends ../layout
 include ../mixins/status-badge
 include ../mixins/resource
 include ../mixins/updates
+include ../mixins/list-controls
 
 block content
   h1.h4.mb-3 Resources
   p.text-body-secondary.small.
     Resources register themselves — start a Client with the shared join key and it appears here. Click a resource for its details, including IP addresses.
 
-  .mb-3
+  .d-flex.flex-wrap.align-items-center.gap-2.mb-3
     +updatesToolbar('client', 'clients', '/resources')
+    .ms-auto
+      +pageSizePicker(list)
+
+  +listToolbar(list, 'resources')
 
   table.table.table-hover.align-middle
     thead
       tr
-        th Name
-        th Type
-        th Version
-        th Status
+        +sortHeader(list, 'name', 'Name')
+        +sortHeader(list, 'type', 'Type')
+        +sortHeader(list, 'version', 'Version', 'desc')
+        +sortHeader(list, 'status', 'Status')
         th Labels
         th Groups
         th Busy source / reason
-        th Last heartbeat
+        +sortHeader(list, 'heartbeat', 'Last heartbeat', 'desc')
         if user.role === 'admin'
           th Actions
     tbody
@@ -44,10 +49,10 @@ block content
           td= fmtDate(r.last_heartbeat_at, 'never')
           if user.role === 'admin'
             td
-              +resourceActions(r, '/resources')
+              +resourceActions(r, list.pageUrl())
 
   each r in resources
-    +resourceCard(r, groupsById, '/resources')
+    +resourceCard(r, groupsById, list.pageUrl())
 
   if user && user.role === 'admin'
     +removeResourceModal()