@andrian.yablonskyy/thub-coordinator 1.0.23 → 1.0.25

package/bin/thub-admin.js

@@ -32,8 +32,9 @@ const { loadConfig } = require('../src/config'),
   { createAdminUsersService } = require('../src/services/admin-users'),
   { createArtifactsService } = require('../src/services/artifacts'),
   { createJobsService } = require('../src/services/jobs'),
+  { createCleanupService } = require('../src/services/cleanup'),
   { generateToken } = require('../src/services/tokens'),
-  { PACKAGES, fetchLatestVersion, isNewer, isValidVersion, npmBin } = require('@andrian.yablonskyy/thub-common'),
+  { PACKAGES, fetchLatestVersion, isNewer, isValidVersion, npmBin, formatDateTime, parseDateTime } = require('@andrian.yablonskyy/thub-common'),
   { spawnSync } = require('node:child_process'),
   { version: installedVersion } = require('../package.json');
 
@@ -44,7 +45,10 @@ function usage(){
   thub-admin join-key generate
   thub-admin resource maintenance <resourceId> --on|--off
   thub-admin jobs reset --yes     Cancel every queued/assigned/preparing/running job
-  thub-admin jobs clean --yes     Permanently delete finished jobs, logs and artifacts
+  thub-admin jobs clean --yes [--before "dd/mm/yyyy HH:MM:SS"]
+                                  Permanently delete finished jobs (with logs and artifacts) and
+                                  history from before then (local time; default: now), then
+                                  compact the database file
   thub-admin group add <name> [--comment <text>]
   thub-admin group list
   thub-admin group remove <groupId>
@@ -192,8 +196,17 @@ function main(){
       console.error('This permanently deletes finished jobs and their logs/artifacts. Re-run with --yes to confirm.');
       process.exit(4);
     }
-    const deleted = jobs.cleanHistory();
-    console.log(`Deleted ${deleted} finished job(s) and their logs/artifacts.`);
+    const before = flags.before ? parseDateTime(flags.before) : new Date();
+    if (!before){
+      console.error(`--before "${flags.before}" isn't a date/time in the dd/mm/yyyy HH:MM:SS format`);
+      process.exit(4);
+    }
+    const r = createCleanupService(db, { jobs, config }).cleanup({ before }),
+      mb = (n) => `${(n / 1024 / 1024).toFixed(1)} MB`;
+    console.log(
+      `Deleted ${r.jobs} finished job(s) and ${r.events} history record(s) from before ${formatDateTime(r.before)}. ` +
+        `Database: ${mb(r.bytesBefore)} -> ${mb(r.bytesAfter)}.`
+    );
     return;
   }
 

package/package.json

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

package/src/api/admin.js

@@ -82,9 +82,15 @@ function createAdminRouter({ services }){
   });
 
   // Permanently deletes finished jobs and their logs/artifacts (§13.1).
+  // Database cleanup (§9): optional `before` (ISO 8601; default now) —
+  // finished jobs that ended before it, older history, then VACUUM.
   router.post('/jobs/clean-history', (req, res) => {
-    const deleted = services.jobs.cleanHistory();
-    res.json({ deleted });
+    const before = req.body?.before ? new Date(req.body.before) : new Date();
+    if (Number.isNaN(before.getTime())){
+      return res.status(400).json({ error: 'before must be an ISO 8601 date/time' });
+    }
+    const r = services.cleanup.cleanup({ before });
+    res.json({ deleted: r.jobs, events: r.events, before: r.before, bytesBefore: r.bytesBefore, bytesAfter: r.bytesAfter });
   });
 
   // Resource groups (§13.1) — membership itself is declared by each

package/src/config.js

@@ -15,7 +15,8 @@
 
 const fs = require('node:fs'),
   os = require('node:os'),
-  path = require('node:path');
+  path = require('node:path'),
+  { JOB_RETENTION } = require('./services/cleanup');
 
 // Defaults mirror README.md §13.
 const DEFAULTS = {
@@ -47,7 +48,12 @@ const DEFAULTS = {
   },
   retention: {
     logRetentionDays: 14,
-    artifactRetentionDays: 30
+    artifactRetentionDays: 30,
+    // How long a finished job (with its logs, artifacts and events) is kept
+    // before the hourly retention task wipes it (services/cleanup.js):
+    // 1w | 2w | 1m | 3m | 6m | forever. `forever` keeps everything until a
+    // manual cleanup (dashboard Clean up database / thub-admin jobs clean).
+    jobRetention: 'forever'
   },
   artifacts: {
     maxUploadMb: 512,
@@ -116,6 +122,13 @@ function loadConfig(configPath = process.env.THUB_COORDINATOR_CONFIG){
     config.clientJoinKey = process.env.THUB_CLIENT_JOIN_KEY;
   }
 
+  if (!Object.hasOwn(JOB_RETENTION, config.retention.jobRetention)){
+    throw new Error(
+      `retention.jobRetention must be one of: ${Object.keys(JOB_RETENTION).join(', ')} ` +
+        `(got ${JSON.stringify(config.retention.jobRetention)}) in ${candidate || 'the config'}`
+    );
+  }
+
   config.configPath = candidate || null;
   config.dataDir = path.resolve(config.dataDir);
 

package/src/server.js

@@ -34,6 +34,7 @@ const path = require('node:path'),
   { createArtifactsService } = require('./services/artifacts'),
   { createCommandsService } = require('./services/commands'),
   { createRetentionService } = require('./services/retention'),
+  { createCleanupService } = require('./services/cleanup'),
   { createUpdatesService } = require('./services/updates'),
 
   { createAgentRouter } = require('./api/agent'),
@@ -55,10 +56,12 @@ function buildServices(config){
     scheduler = createScheduler(db, { bus, events, registry, config }),
     heartbeatMonitor = createHeartbeatMonitor(db, { bus, events, registry, jobs, config }),
     retention = createRetentionService(db, { bus, logs, artifacts, config }),
+    cleanup = createCleanupService(db, { jobs, config }),
     updates = createUpdatesService({ config });
 
   jobs.reconcileOnStartup();
   updates.start();
+  cleanup.start();
 
   const sweepInterval = setInterval(() => {
     jobs.checkAssignAcks();
@@ -81,6 +84,7 @@ function buildServices(config){
     scheduler,
     heartbeatMonitor,
     retention,
+    cleanup,
     updates
   };
 }

package/src/services/cleanup.js

@@ -0,0 +1,147 @@
+/**
+ * @file        packages/coordinator/src/services/cleanup.js
+ * @description Database cleanup: wipe finished jobs (logs, artifacts, events) and old events before a cutoff, then
+ *              VACUUM to shrink the file — on demand from the dashboard, and hourly per retention.jobRetention (README §9)
+ *
+ * @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 fs = require('node:fs');
+
+// retention.jobRetention values: how long a finished job is kept. `forever`
+// means only a manual cleanup (dashboard / POST /admin/jobs/clean-history)
+// removes jobs. Months are calendar months.
+const JOB_RETENTION = {
+    '1w': { days: 7, label: '1 week' },
+    '2w': { days: 14, label: '2 weeks' },
+    '1m': { months: 1, label: '1 month' },
+    '3m': { months: 3, label: '3 months' },
+    '6m': { months: 6, label: '6 months' },
+    forever: { label: 'indefinitely' }
+  },
+  PRUNE_INTERVAL_MS = 3600 * 1000,
+  FIRST_PRUNE_DELAY_MS = 60 * 1000,
+  // VACUUM rewrites the whole file and blocks meanwhile — the automatic
+  // task does it at most this often; a manual cleanup always does.
+  AUTO_VACUUM_MIN_INTERVAL_MS = 24 * 3600 * 1000;
+
+// `now` minus `amount` ({days} or {months}), in UTC so the server's own
+// time zone and its DST changes don't shift the cutoff by an hour.
+function subtract(now, { days, months }){
+  const d = new Date(now);
+  if (months){
+    d.setUTCMonth(d.getUTCMonth() - months);
+  }
+  if (days){
+    d.setUTCDate(d.getUTCDate() - days);
+  }
+  return d;
+}
+
+// Cutoff for a retention setting: jobs that finished before it go. null for
+// `forever`. Throws on an unknown setting (config.js validates it at load).
+function retentionCutoff(setting, now = new Date()){
+  const def = JOB_RETENTION[setting];
+  if (!def){
+    throw new Error(`retention.jobRetention must be one of: ${Object.keys(JOB_RETENTION).join(', ')} (got "${setting}")`);
+  }
+  return def.days || def.months ? subtract(now, def) : null;
+}
+
+function createCleanupService(db, { jobs, config, now = () => new Date() }){
+  let lastVacuumAt = 0,
+    timer = null,
+    firstRun = null;
+
+  // thub.db plus its WAL — what the database takes on disk.
+  function databaseBytes(){
+    return [config.dbPath, `${config.dbPath}-wal`].reduce((sum, file) => {
+      try {
+        return sum + fs.statSync(file).size;
+      }
+      catch {
+        return sum;
+      }
+    }, 0);
+  }
+
+  function vacuum(){
+    db.pragma('wal_checkpoint(TRUNCATE)');
+    db.exec('VACUUM');
+    db.pragma('wal_checkpoint(TRUNCATE)');
+    lastVacuumAt = Date.now();
+  }
+
+  // Wipe everything older than `before` (a Date; default now): finished
+  // jobs that ended before it, with their logs, artifacts and events, and
+  // the other audit events (resource/agent/group) logged before it. Events
+  // of jobs that stay (still active, or newer) are kept. `vacuum`: true,
+  // false, or 'auto' (only if something was deleted and the last VACUUM is
+  // over a day old). Returns what was done, with the size before/after.
+  function cleanup({ before = now(), vacuum: doVacuum = true } = {}){
+    const cutoff = before.toISOString(),
+      bytesBefore = config.dbPath ? databaseBytes() : 0,
+      deletedJobs = jobs.purgeFinishedBefore(cutoff),
+      deletedEvents = db.prepare(
+        `DELETE FROM events WHERE ts < ?
+           AND NOT (entity = 'job' AND entity_id IN (SELECT id FROM jobs))
+           AND NOT (entity = 'job' AND entity_id = 'bulk' AND type = 'jobs.cleaned')`
+      ).run(cutoff).changes,
+      vacuumed = doVacuum === true ||
+        (doVacuum === 'auto' && deletedJobs + deletedEvents > 0 && Date.now() - lastVacuumAt >= AUTO_VACUUM_MIN_INTERVAL_MS);
+    if (vacuumed){
+      vacuum();
+    }
+    return { before: cutoff, jobs: deletedJobs, events: deletedEvents, vacuumed, bytesBefore, bytesAfter: config.dbPath ? databaseBytes() : 0 };
+  }
+
+  // The retention task: hourly (first run a minute after start), wipes jobs
+  // older than retention.jobRetention. Does nothing for `forever`.
+  function prune(){
+    const cutoff = retentionCutoff(config.retention.jobRetention, now());
+    if (!cutoff){
+      return null;
+    }
+    const result = cleanup({ before: cutoff, vacuum: 'auto' });
+    if (result.jobs || result.events){
+      console.log(
+        `Retention (${JOB_RETENTION[config.retention.jobRetention].label}): removed ${result.jobs} job(s) and ${result.events} event(s) ` +
+          `from before ${result.before}${result.vacuumed ? `; database ${result.bytesBefore} -> ${result.bytesAfter} bytes` : ''}`
+      );
+    }
+    return result;
+  }
+
+  function safePrune(){
+    try {
+      prune();
+    }
+    catch (err){
+      console.error(`Retention cleanup failed: ${err.message}`);
+    }
+  }
+
+  function start(){
+    firstRun = setTimeout(safePrune, FIRST_PRUNE_DELAY_MS);
+    firstRun.unref?.();
+    timer = setInterval(safePrune, PRUNE_INTERVAL_MS);
+    timer.unref?.();
+  }
+
+  function stop(){
+    clearTimeout(firstRun);
+    clearInterval(timer);
+  }
+
+  return { cleanup, prune, databaseBytes, start, stop };
+}
+
+module.exports = { createCleanupService, retentionCutoff, JOB_RETENTION };

package/src/services/jobs.js

@@ -145,7 +145,27 @@ function createJobsService(db, { bus, events, registry, artifacts, config }){
       spec.target.client = resource.id;
     }
 
-    if (!registry.everSatisfiable(spec.target.type, spec.target.labels, spec.target.group, spec.target.client)){
+    // A job-supplied Docker image or command needs a Client that opted in —
+    // say which, rather than the generic "no resource can satisfy".
+    const needs = { jobImage: Boolean(spec.firmware.image), jobCommand: Boolean(spec.tests.command) },
+      { type, labels, group, client } = spec.target;
+    if ((needs.jobImage || needs.jobCommand) && registry.everSatisfiable(type, labels, group, client) &&
+      !registry.everSatisfiable(type, labels, group, client, needs)){
+      const missing = [
+        needs.jobImage && !registry.everSatisfiable(type, labels, group, client, { jobImage: true }) &&
+          `job-supplied Docker images (${spec.firmware.image}) — "sw": { "allowJobImages": true }`,
+        needs.jobCommand && !registry.everSatisfiable(type, labels, group, client, { jobCommand: true }) &&
+          'job-supplied commands (--run) — "allowJobCommands": true'
+      ].filter(Boolean);
+      throw Object.assign(
+        new Error(
+          `No matching Client runs ${missing.length ? missing.join(', nor ') : 'both a job-supplied Docker image and command together'}` +
+            ' — enable it in a Client\'s config'
+        ),
+        { status: 422 }
+      );
+    }
+    if (!registry.everSatisfiable(type, labels, group, client, needs)){
       throw Object.assign(
         new Error(
           `No registered resource can ever satisfy type=${spec.target.type} labels=${spec.target.labels.join(',')}` +
@@ -416,24 +436,38 @@ function createJobsService(db, { bus, events, registry, artifacts, config }){
   // not just active work, needs clearing out. Unlike the nightly retention
   // sweep (§9), this runs on demand and isn't limited to old jobs.
   function cleanHistory(){
+    return purgeFinishedBefore(null);
+  }
+
+  // Finished jobs that ended before `beforeIso` (null: all of them), with
+  // their logs, artifacts (files too) and events — manual cleanup and the
+  // job retention task (services/cleanup.js). Active jobs are never touched.
+  function purgeFinishedBefore(beforeIso){
     const placeholders = [...TERMINAL_JOB_STATES].map(() => '?').join(','),
-      rows = db.prepare(`SELECT id FROM jobs WHERE state IN (${placeholders})`).all(...TERMINAL_JOB_STATES),
+      rows = beforeIso
+        ? db.prepare(`SELECT id FROM jobs WHERE state IN (${placeholders}) AND COALESCE(finished_at, created_at) < ?`)
+          .all(...TERMINAL_JOB_STATES, beforeIso)
+        : db.prepare(`SELECT id FROM jobs WHERE state IN (${placeholders})`).all(...TERMINAL_JOB_STATES),
       ids = rows.map((r) => r.id);
     if (ids.length === 0){
       return 0;
     }
 
-    const tx = db.transaction(() => {
-      for (const id of ids){
-        artifacts.deleteJobArtifacts(id);
-        db.prepare('DELETE FROM artifacts WHERE job_id = ?').run(id);
-        db.prepare('DELETE FROM job_logs WHERE job_id = ?').run(id);
-        db.prepare('DELETE FROM events WHERE entity = \'job\' AND entity_id = ?').run(id);
-        db.prepare('DELETE FROM jobs WHERE id = ?').run(id);
-      }
-    });
+    const deleteArtifacts = db.prepare('DELETE FROM artifacts WHERE job_id = ?'),
+      deleteLogs = db.prepare('DELETE FROM job_logs WHERE job_id = ?'),
+      deleteEvents = db.prepare('DELETE FROM events WHERE entity = \'job\' AND entity_id = ?'),
+      deleteJob = db.prepare('DELETE FROM jobs WHERE id = ?'),
+      tx = db.transaction(() => {
+        for (const id of ids){
+          artifacts.deleteJobArtifacts(id);
+          deleteArtifacts.run(id);
+          deleteLogs.run(id);
+          deleteEvents.run(id);
+          deleteJob.run(id);
+        }
+      });
     tx();
-    events.record('job', 'bulk', 'jobs.cleaned', { count: ids.length });
+    events.record('job', 'bulk', 'jobs.cleaned', { count: ids.length, before: beforeIso });
     return ids.length;
   }
 
@@ -470,7 +504,8 @@ function createJobsService(db, { bus, events, registry, artifacts, config }){
     reconcileOnStartup,
     resetQueue,
     countActiveAndFinished,
-    cleanHistory
+    cleanHistory,
+    purgeFinishedBefore
   };
 }
 

package/src/services/registry.js

@@ -67,10 +67,16 @@ const MAX_DEVICES = 8,
     present: typeof d?.present === 'boolean' ? d.present : null
   });
 
+// Plus `allowJobCommands` (either type): runs a job's own `tests.command`.
 function sanitizeCapabilities(caps){
   if (!caps || typeof caps !== 'object'){
     return null;
   }
+  const typed = sanitizeTypedCapabilities(caps);
+  return typed ? { ...typed, allowJobCommands: caps.allowJobCommands === true } : null;
+}
+
+function sanitizeTypedCapabilities(caps){
   if (caps.sw && typeof caps.sw === 'object'){
     const sw = caps.sw;
     return {
@@ -78,6 +84,7 @@ function sanitizeCapabilities(caps){
         image: str(sw.image),
         registry: str(sw.registry),
         allowDockerHub: sw.allowDockerHub === true,
+        allowJobImages: sw.allowJobImages === true,
         cpus: num(sw.cpus),
         memory: str(sw.memory, 16)
       }
@@ -468,10 +475,15 @@ function createRegistryService(db, { bus, events }){
     );
   }
 
-  function matchesTarget(r, labels, groupId, resourceId){
+  // `needs`: what a job brings that a Client must have opted in to run —
+  // jobImage (firmware.image; sw.allowJobImages) and jobCommand
+  // (tests.command; allowJobCommands).
+  function matchesTarget(r, labels, groupId, resourceId, needs = {}){
     return labels.every((l) => r.labels.includes(l)) &&
       (!groupId || r.group_ids.includes(groupId)) &&
-      (!resourceId || r.id === resourceId);
+      (!resourceId || r.id === resourceId) &&
+      (!needs.jobImage || r.capabilities?.sw?.allowJobImages === true) &&
+      (!needs.jobCommand || r.capabilities?.allowJobCommands === true);
   }
 
   // Admin: remove a resource from the registry (dashboard "Remove"). Refused
@@ -509,17 +521,17 @@ function createRegistryService(db, { bus, events }){
     return db.prepare('SELECT * FROM resources WHERE remove_requested_at IS NOT NULL').all().map(rowToResource);
   }
 
-  function findIdleCandidates(type, labels, groupId, resourceId){
+  function findIdleCandidates(type, labels, groupId, resourceId, needs){
     const rows = db
       .prepare('SELECT * FROM resources WHERE status = ? AND type = ? AND remove_requested_at IS NULL')
       .all(RESOURCE_STATES.IDLE, type)
       .map(rowToResource);
-    return rows.filter((r) => matchesTarget(r, labels, groupId, resourceId));
+    return rows.filter((r) => matchesTarget(r, labels, groupId, resourceId, needs));
   }
 
-  function everSatisfiable(type, labels, groupId, resourceId){
+  function everSatisfiable(type, labels, groupId, resourceId, needs){
     const rows = db.prepare('SELECT * FROM resources WHERE type = ?').all(type).map(rowToResource);
-    return rows.some((r) => matchesTarget(r, labels, groupId, resourceId));
+    return rows.some((r) => matchesTarget(r, labels, groupId, resourceId, needs));
   }
 
   return {

package/src/services/scheduler.js

@@ -15,6 +15,11 @@
 
 const { JOB_STATES, BUSY_SOURCES } = require('@andrian.yablonskyy/thub-common');
 
+// What a job needs a Client to have opted in to (registry matchesTarget).
+function jobNeeds(spec){
+  return { jobImage: Boolean(spec.firmware?.image), jobCommand: Boolean(spec.tests?.command) };
+}
+
 function rowToJob(row){
   return { ...row, spec: JSON.parse(row.spec) };
 }
@@ -43,7 +48,7 @@ function createScheduler(db, { bus, events, registry, config }){
         for (const job of queued){
           const { type, labels = [], group, client } = job.spec.target,
             candidates = registry
-              .findIdleCandidates(type, labels, group, client)
+              .findIdleCandidates(type, labels, group, client, jobNeeds(job.spec))
               .filter((r) => !claimedResourceIds.has(r.id));
           if (candidates.length === 0){
             continue;

package/src/web/routes.js

@@ -20,7 +20,10 @@ const fs = require('node:fs'),
   multer = require('multer'),
   { requireAdminSession, requireAdminRole } = require('../auth'),
   { attachJobStream } = require('../api/sse'),
-  { RESOURCE_STATES, JOB_STATES, ACTIVE_JOB_STATES, isNewer, compareVersions, formatDateTime } = require('@andrian.yablonskyy/thub-common'),
+  {
+    RESOURCE_STATES, JOB_STATES, ACTIVE_JOB_STATES, TERMINAL_JOB_STATES, isNewer, compareVersions, formatDateTime, parseDateTime
+  } = require('@andrian.yablonskyy/thub-common'),
+  { retentionCutoff, JOB_RETENTION } = require('../services/cleanup'),
   listPrefs = require('../services/list-prefs');
 
 // Resources page sort keys (list-prefs.js) -> comparators. Empty values
@@ -92,6 +95,31 @@ function createWebRouter({ services, config }){
     return { prefs, urlFor, pageSizes: listPrefs.PAGE_SIZES };
   }
 
+  // What the Clean up database modal shows: current size, the oldest
+  // finished job, the retention setting, and quick-pick cutoffs — all
+  // formatted in the user's time zone, like the cutoff field itself.
+  function cleanupInfo(req){
+    const tz = req.session.user.timezone || 'UTC',
+      fmt = (d) => formatDateTime(d, { timeZone: tz }),
+      now = new Date(),
+      oldest = services.db.prepare(
+        `SELECT MIN(COALESCE(finished_at, created_at)) AS at FROM jobs
+         WHERE state IN (${[...TERMINAL_JOB_STATES].map(() => '?').join(',')})`
+      ).get(...TERMINAL_JOB_STATES).at,
+      retention = config.retention.jobRetention;
+    return {
+      size: `${(services.cleanup.databaseBytes() / 1024 / 1024).toFixed(1)} MB`,
+      oldestFinished: oldest ? fmt(oldest) : null,
+      now: fmt(now),
+      retention,
+      retentionLabel: JOB_RETENTION[retention]?.label,
+      presets: [
+        { label: 'Everything (now)', value: fmt(now) },
+        ...['1w', '1m', '3m', '6m'].map((k) => ({ label: `Older than ${JOB_RETENTION[k].label}`, value: fmt(retentionCutoff(k, now)) }))
+      ]
+    };
+  }
+
   // 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) }));
@@ -507,8 +535,9 @@ function createWebRouter({ services, config }){
       // 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
+      // For the Reset queue / Clean up database confirmation modals.
+      jobCounts: req.session.user.role === 'admin' ? services.jobs.countActiveAndFinished() : null,
+      cleanupInfo: req.session.user.role === 'admin' ? cleanupInfo(req) : null
     });
   });
 
@@ -521,9 +550,30 @@ function createWebRouter({ services, config }){
     res.redirect('/jobs');
   });
 
+  // "Clean up database" (§9): everything before the given time — finished
+  // jobs with their logs/artifacts, and older history — then VACUUM. The
+  // time is dd/mm/yyyy HH:MM:SS in the user's own time zone.
   router.post('/jobs/clean-history', requireAdminRole, (req, res) => {
-    const deleted = services.jobs.cleanHistory();
-    flash(req, 'warning', `Deleted ${deleted} finished job(s) and their logs/artifacts.`);
+    const tz = req.session.user.timezone || 'UTC',
+      text = String(req.body.before || '').trim(),
+      before = text ? parseDateTime(text, { timeZone: tz }) : new Date();
+    if (!before){
+      flash(req, 'danger', `"${text}" isn't a date/time in the dd/mm/yyyy HH:MM:SS format — nothing was deleted.`);
+      return res.redirect('/jobs');
+    }
+    try {
+      const r = services.cleanup.cleanup({ before }),
+        mb = (n) => `${(n / 1024 / 1024).toFixed(1)} MB`;
+      flash(
+        req,
+        'warning',
+        `Deleted ${r.jobs} finished job(s) and ${r.events} history record(s) from before ` +
+          `${formatDateTime(r.before, { timeZone: tz })}. Database: ${mb(r.bytesBefore)} → ${mb(r.bytesAfter)}.`
+      );
+    }
+    catch (err){
+      flash(req, 'danger', `Cleanup failed: ${err.message}`);
+    }
     res.redirect('/jobs');
   });
 

package/test/cleanup.test.js

@@ -0,0 +1,125 @@
+/**
+ * @file        packages/coordinator/test/cleanup.test.js
+ * @description Tests: database cleanup before a cutoff, job retention settings, and the retention task
+ *
+ * @author      Andrian Yablonskyy
+ * @copyright   Copyright (c) 2026 Andrian Yablonskyy. All rights reserved.
+ *
+ * This file is part of TestHub and is proprietary and confidential.
+ * Unauthorized copying, modification, distribution, or use of this file,
+ * via any medium, is strictly prohibited without prior written permission
+ * from AdSystem.PRO.
+ */
+
+'use strict';
+
+const test = require('node:test'),
+  assert = require('node:assert/strict'),
+  fs = require('node:fs'),
+  os = require('node:os'),
+  path = require('node:path'),
+  { EventEmitter } = require('node:events'),
+  { openDb } = require('../src/db'),
+  { createEventsService } = require('../src/services/events'),
+  { createRegistryService } = require('../src/services/registry'),
+  { createAgentsService } = require('../src/services/agents'),
+  { createArtifactsService } = require('../src/services/artifacts'),
+  { createJobsService } = require('../src/services/jobs'),
+  { createCleanupService, retentionCutoff } = require('../src/services/cleanup'),
+  { JOB_STATES } = require('@andrian.yablonskyy/thub-common');
+
+const NOW = new Date('2026-09-28T12:00:00Z');
+
+function setup(jobRetention = 'forever'){
+  const dataDir = fs.mkdtempSync(path.join(os.tmpdir(), 'thub-cleanup-')),
+    config = {
+      dataDir,
+      dbPath: path.join(dataDir, 'thub.db'),
+      artifactsDir: path.join(dataDir, 'artifacts'),
+      artifacts: { linkTtlHours: 1 },
+      sessionSecret: 's',
+      publicUrl: 'http://x',
+      scheduler: { maxQueuedPerAgent: 1000 },
+      jobs: { defaultTimeoutSec: 60, maxTimeoutSec: 60 },
+      retention: { jobRetention }
+    },
+    db = openDb(config.dbPath),
+    bus = new EventEmitter(),
+    events = createEventsService(db),
+    registry = createRegistryService(db, { bus, events }),
+    { agent } = createAgentsService(db, { events }).create({ name: 'ci', kind: 'ci' }),
+    artifacts = createArtifactsService(db, { config }),
+    jobs = createJobsService(db, { bus, events, registry, artifacts, config }),
+    cleanup = createCleanupService(db, { jobs, config, now: () => NOW });
+  registry.registerAuto({ clientId: 'c', name: 'lab', type: 'sw', labels: [] });
+
+  // A job that finished at `finishedAt` (or is still queued, if null), with a log line.
+  function job(finishedAt){
+    const spec = { target: { type: 'sw' }, firmware: { url: 'https://x/a' }, tests: { url: 'https://x/t' } },
+      j = jobs.create({ agentId: agent.id, source: 'cli', spec });
+    db.prepare('INSERT INTO job_logs (job_id, seq, ts, stream, line) VALUES (?, 1, ?, \'runner\', ?)').run(j.id, NOW.toISOString(), 'x'.repeat(2000));
+    if (finishedAt){
+      jobs.setState(j.id, JOB_STATES.PASSED);
+      db.prepare('UPDATE jobs SET finished_at = ? WHERE id = ?').run(finishedAt, j.id);
+    }
+    return j.id;
+  }
+  const exists = (id) => !!jobs.get(id),
+    eventAt = (entity, ts) => db.prepare('INSERT INTO events (ts, entity, entity_id, type) VALUES (?, ?, \'x\', \'t\')').run(ts, entity).lastInsertRowid;
+  return { db, jobs, cleanup, job, exists, eventAt };
+}
+
+test('retentionCutoff: days, calendar months, and forever', () => {
+  assert.equal(retentionCutoff('1w', NOW).toISOString(), '2026-09-21T12:00:00.000Z');
+  assert.equal(retentionCutoff('2w', NOW).toISOString(), '2026-09-14T12:00:00.000Z');
+  assert.equal(retentionCutoff('1m', NOW).toISOString(), '2026-08-28T12:00:00.000Z');
+  assert.equal(retentionCutoff('6m', NOW).toISOString(), '2026-03-28T12:00:00.000Z');
+  assert.equal(retentionCutoff('forever', NOW), null);
+  assert.throws(() => retentionCutoff('1y', NOW), /must be one of/);
+});
+
+test('cleanup wipes finished jobs and history before the cutoff, keeps the rest, and compacts the file', () => {
+  const { db, cleanup, job, exists, eventAt } = setup(),
+    old = Array.from({ length: 40 }, () => job('2026-01-10T00:00:00Z')),
+    recent = job('2026-09-27T00:00:00Z'),
+    active = job(null),
+    oldResourceEvent = eventAt('resource', '2026-01-01T00:00:00Z'),
+    newResourceEvent = eventAt('resource', '2026-09-27T00:00:00Z'),
+
+    r = cleanup.cleanup({ before: new Date('2026-06-01T00:00:00Z') });
+  assert.equal(r.jobs, 40);
+  assert.ok(old.every((id) => !exists(id)));
+  assert.ok(exists(recent) && exists(active));
+  assert.equal(db.prepare('SELECT COUNT(*) AS n FROM job_logs').get().n, 2); // recent + active only
+  const eventIds = db.prepare('SELECT id FROM events').all().map((e) => e.id);
+  assert.ok(!eventIds.includes(oldResourceEvent) && eventIds.includes(newResourceEvent));
+  assert.equal(r.vacuumed, true);
+  assert.ok(r.bytesAfter < r.bytesBefore, `${r.bytesAfter} < ${r.bytesBefore}`);
+});
+
+test('an old but still active job is never wiped, nor its events', () => {
+  const { db, cleanup, job, exists } = setup(),
+    active = job(null);
+  db.prepare('UPDATE jobs SET created_at = ? WHERE id = ?').run('2020-01-01T00:00:00Z', active);
+  db.prepare('UPDATE events SET ts = ? WHERE entity_id = ?').run('2020-01-01T00:00:00Z', active);
+  cleanup.cleanup({ before: NOW });
+  assert.ok(exists(active));
+  assert.ok(db.prepare('SELECT COUNT(*) AS n FROM events WHERE entity_id = ?').get(active).n > 0);
+});
+
+test('the retention task wipes per jobRetention, and does nothing for forever', () => {
+  const kept = setup('forever'),
+    id = kept.job('2025-01-01T00:00:00Z');
+  assert.equal(kept.cleanup.prune(), null);
+  assert.ok(kept.exists(id));
+
+  const pruned = setup('1m'),
+    tooOld = pruned.job('2026-08-01T00:00:00Z'),
+    young = pruned.job('2026-09-01T00:00:00Z'),
+    r = pruned.cleanup.prune();
+  assert.equal(r.before, '2026-08-28T12:00:00.000Z');
+  assert.ok(!pruned.exists(tooOld) && pruned.exists(young));
+  assert.equal(r.vacuumed, true); // first automatic run: compacts
+  pruned.job('2026-08-02T00:00:00Z');
+  assert.equal(pruned.cleanup.prune().vacuumed, false); // at most once a day
+});

package/test/scheduler.test.js

@@ -525,6 +525,46 @@ test('a removed Client re-registers as a fresh resource under the same name', ()
   assert.equal(again.name, 'lab-back');
 });
 
+test('a job-supplied Docker image only goes to SW Clients that allow it; otherwise 422', () => {
+  const { registry, agents, jobs, scheduler } = buildTestServices(),
+    { agent } = agents.create({ name: 'dev', kind: 'cli' }),
+    imageJob = { target: { type: 'sw', labels: [] }, firmware: { image: 'alpine' }, tests: { url: 'https://x/t.tar.gz' } },
+    strict = registerResource(registry, { name: 'sw-strict', type: 'sw' });
+  registry.heartbeat(strict.id, { state: 'idle' });
+
+  assert.throws(() => jobs.create({ agentId: agent.id, source: 'cli', spec: imageJob }), /allowJobImages/);
+
+  const { resourceId } = registry.registerAuto({
+    clientId: 'c-open', name: 'sw-open', type: 'sw', labels: [], capabilities: { sw: { image: 'emu', allowJobImages: true } }
+  });
+  registry.heartbeat(resourceId, { state: 'idle' });
+  const job = jobs.create({ agentId: agent.id, source: 'cli', spec: imageJob });
+  scheduler.runPass();
+  assert.equal(jobs.get(job.id).resource_id, resourceId); // not sw-strict, though it's idle too
+
+  const fileJob = jobs.create({ agentId: agent.id, source: 'cli', spec: makeSpec() });
+  scheduler.runPass();
+  assert.equal(jobs.get(fileJob.id).resource_id, strict.id); // firmware URLs still go anywhere
+});
+
+test('a job-supplied command only goes to Clients with allowJobCommands; otherwise 422 naming it', () => {
+  const { registry, agents, jobs, scheduler } = buildTestServices(),
+    { agent } = agents.create({ name: 'dev', kind: 'cli' }),
+    commandJob = makeSpec({ tests: { url: 'https://x/t.tar.gz', command: 'make test' } }),
+    plain = registerResource(registry, { name: 'sw-plain', type: 'sw' });
+  registry.heartbeat(plain.id, { state: 'idle' });
+
+  assert.throws(() => jobs.create({ agentId: agent.id, source: 'cli', spec: commandJob }), /allowJobCommands/);
+
+  const { resourceId } = registry.registerAuto({
+    clientId: 'c-cmd', name: 'sw-cmd', type: 'sw', labels: [], capabilities: { sw: { image: 'emu' }, allowJobCommands: true }
+  });
+  registry.heartbeat(resourceId, { state: 'idle' });
+  const job = jobs.create({ agentId: agent.id, source: 'cli', spec: commandJob });
+  scheduler.runPass();
+  assert.equal(jobs.get(job.id).resource_id, resourceId);
+});
+
 test('a resource can belong to several groups at once', () => {
   const { registry, groups } = buildTestServices(),
     g1 = groups.create({ name: 'g1' }),

package/views/jobs/list.pug

@@ -9,7 +9,7 @@ block content
     if canManage
       .btn-group
         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
+        button.btn.btn-sm.btn-outline-danger.ms-1(type="button" data-bs-toggle="modal" data-bs-target="#clean-history-modal") Clean up database
 
   form.row.g-2.mb-3(method="get")
     .col-auto
@@ -90,22 +90,57 @@ block content
 
     +confirmModal({
       id: 'clean-history-modal',
+      formId: 'cleanup-form',
       tone: 'danger',
       icon: 'bi-trash3-fill',
-      title: 'Clean job history?',
+      title: 'Clean up the database?',
       action: '/jobs/clean-history',
-      confirmLabel: 'Delete finished jobs',
-      confirmIcon: 'bi-trash3',
-      disabled: !jobCounts.finished
+      confirmLabel: 'Delete and compact',
+      confirmIcon: 'bi-trash3'
     })
-      if jobCounts.finished
-        p
-          | This permanently deletes
+      p.small.text-body-secondary
+        | Database size:
+        |
+        strong= cleanupInfo.size
+        | . Finished jobs:
+        |
+        strong= jobCounts.finished
+        if cleanupInfo.oldestFinished
+          |  (oldest from #{cleanupInfo.oldestFinished})
+        | .
+      label.form-label(for="cleanup-before") Delete everything before
+      input.form-control#cleanup-before(
+        type="text"
+        name="before"
+        form="cleanup-form"
+        value=cleanupInfo.now
+        required
+        pattern="\\s*\\d{1,2}/\\d{1,2}/\\d{4}( +\\d{1,2}:\\d{2}(:\\d{2})?)?\\s*"
+        placeholder="dd/mm/yyyy HH:MM:SS"
+        aria-describedby="cleanup-before-help"
+      )
+      .form-text#cleanup-before-help
+        | dd/mm/yyyy HH:MM:SS, 24-hour, in your time zone (#{userTimeZone}).
+      .d-flex.flex-wrap.gap-1.mt-2.mb-3
+        each preset in cleanupInfo.presets
+          button.btn.btn-sm.btn-outline-secondary(
+            type="button"
+            data-value=preset.value
+            onclick="document.getElementById('cleanup-before').value = this.dataset.value"
+          )= preset.label
+      p
+        | Deletes finished jobs that ended before then, with their logs and artifacts (files too), and the resource, agent and group history logged before then — then compacts the database file.
+        |
+        strong This cannot be undone.
+        |  Active jobs are never touched.
+      p.small.text-body-secondary.mb-0
+        i.bi.bi-clock-history.me-1
+        if cleanupInfo.retention === 'forever'
+          | Automatic cleanup is off: finished jobs are kept indefinitely. Set
           |
-          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.
+          code retention.jobRetention
+          |  in coordinator.json (1w, 2w, 1m, 3m, 6m) to wipe older ones every hour.
+        else
+          | Automatic cleanup: finished jobs are kept for #{cleanupInfo.retentionLabel} (
+          code retention.jobRetention
+          | ) and older ones are wiped every hour.

package/views/mixins/confirm-modal.pug

@@ -3,7 +3,8 @@
 //- 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).
+//- disabled (nothing to do — the confirm button is disabled), formId (id of
+//- the footer form, so inputs in the body can join it with form=<formId>).
 mixin confirmModal(opts)
   - const tone = opts.tone || 'danger'
   .modal.fade(id=opts.id tabindex="-1" aria-labelledby=`${opts.id}-title` aria-hidden="true")
@@ -19,7 +20,7 @@ mixin confirmModal(opts)
           block
         .modal-footer
           button.btn.btn-secondary(type="button" data-bs-dismiss="modal") Keep
-          form(method="post" action=opts.action)
+          form(method="post" action=opts.action id=opts.formId)
             button.btn(type="submit" class=`btn-${tone}` disabled=opts.disabled)
               if opts.confirmIcon
                 i.bi.me-1(class=opts.confirmIcon)