dcp-worker 4.1.1 → 4.2.0

package/bin/dcp-worker

@@ -1,5 +1,4 @@
 #! /usr/bin/env node
-
 /**
  *  @file       dcp-worker.js
  *              Standalone NodeJS DCP Worker
@@ -9,571 +8,725 @@
  *              Wes Garland, wes@distributive.network
  *
  *  @date       April 2020
- *              April-May 2023
- *              May-June 2023
+ *              April-May 2023, May-June 2023
+ *              June 2024, June 2025
  */
 'use strict';
-
 var worker;
 
 const process = require('process');
 const fs      = require('fs');
 const path    = require('path');
-const telnetd = require('../lib/remote-console');
-
-const { slicesFetched, debugging, displayMaxDiagInfo } = require('../lib/utils');
-const { a$sleep, leafMergeInto } = require('dcp/utils');
+const debug   = require('debug');
+const telnetd = require('../lib/telnetd');
+const httpd   = require('../lib/web-console');
+const pidfile = require('../lib/pidfile');
+const reports = require('../lib/reports');
+const utils   = require('../lib/utils');
+const loggers = require('../lib/loggers');
+var wallet, identity, a$sleep, DistributiveWorker; /* populate in main() */
+
+const { exitCodes,
+        logLevels }          = require('../lib/consts');
 
-const EXIT_UNHANDLED = 5;
 const systemStateInfo = globalThis.systemStateInfo = {};
+const usingDebugger = require('module')._cache.niim instanceof require('module').Module;
+
+process.on('SIGESC',  handleSigDeath); /* synthetic; for dashboard <esc> keystrokes */
+process.on('SIGINT',  handleSigDeath);
+process.on('SIGTERM', handleSigDeath);
+process.on('SIGQUIT', handleSigDeath);
+process.on('unhandledRejection', handleUnhandled);
+process.on('uncaughtException',  handleUnhandled);
 
 /* Setup the telnet REPL up early to ensure early-failure log messages are captured */
 const replHelpers = {
   help: {
-    report: 'Print a worker status & slice report',
-    kill:   'Try to kill the worker',
-    die:    'Kill the worker',
+    report: 'Print slice report',
+    kill:   'Exit the process immediately',
     debug:  'Set DCP_DEBUG value and re-initialize debugging scopes',
   },
   commands: {
-    report: printReport,
-    kill:   processExit,
-    die:    () => worker && worker.stop(),
+    report: () => reports.printSliceReport(worker),
+    kill:   (exitCode) => process.exit(Number(exitCode)),
     debug:  (value) => require('dcp/internal/debugging').reinit(value),
   },
 };
 telnetd.init(replHelpers);
 require('dcp-client').init().then(main).catch(handleUnhandled);
 
-/**
- * Output startup banner message. Currently a wrapper for console.log, future plans are to make it
- * possible to suppress these messages, and also to send them multiple places (eg tty and syslog)
- */
-function bannerLog()
+function usage()
 {
-  console.log.apply(console, arguments);
-  bannerLog.cumulative.push(arguments);
+  console.log(`
+DCP Worker: Join the DCP network as a compute supplier.
+Copyright (c) 2018-2025, Distributive Corp. Released under the terms of the MIT License.
+
+Usage: ${path.basename(__filename)} [options...]
+Options:
+  -h, --help                         Display this help and exit
+      --dcp-identity=string          Identity key, in hexadecimal
+      --dcp-identity=json            Identity keystore, in json format
+      --dcp-identity=filename        Name of file containing identity keystore
+      --earnings-account=string      Bank account into which to deposit earnings
+      --earnings-account=keystore    Keystore, in json format, for bank account
+      --earnings-account=filename    Name of file containing bank account keystore
+  -c, --cores=[#cpu][,#gpu]          Override detected number of CPU and GPU
+                                     cores available to the evaluator.
+  -u, --utilization=[cpu][,gpu]      default proportion of CPU,GPU to utilize: eg use
+                                     -u 0.8,0.75 for 80% CPU and 75% GPU utilization
+  -m, --max-sandboxes=integer        Override the default Maximum number of sandboxes
+  -H, --hostname                     Override evaluator hostname
+  -p, --port                         Override evaluator port number
+  -o, --output=mode                  Set the console mode: text, dashboard, or none
+  -l, --logger=type                  Add an additional logger: syslog, logfile (all
+                                     platforms), event-log (win32)
+      --logfile=filename             Change filename, implies --logger=logfile
+      --overwrite-logfile            Overwrite previous log files instead of appending
+      --syslog=url                   Change syslog url, implies --logger=syslog. Syslog
+                                     facility (eg. local7) is the URL pathname.
+      --syslog=facility              Change syslog facility, implies --logger=syslog.
+      --min-level=[logger,]level     Set the lowest level of log sent to a given logger
+      --min-level=[console,]level    Set the lowest level of log sent to the console
+  -j, --job                          Restrict worker to a specific set of jobs. Use more
+                                     than once for multiple jobs.
+  -g, --join=                        Join a compute group; the format is
+                                     "joinKey,joinSecret" or "joinKey,eh1-joinHash".
+                                     Use more than once to join multiple groups.
+  -a, --allow-origin=origin          Grant all jobs network access to specified origin
+                                     Use more than once for multiple origins.
+      --zero-trust                   Do not load configuration data from scheduler
+      --no-global                    Do not fetch work from the Global Compute Group
+      --show=                        Show configuration data and exit. Valid arguments:
+                                      - worker-id: the worker id
+                                      - identity: the address of the active DCP identity
+                                      - earnings-account: where funds will be deposited
+                                      - owner: the address of the registered owner
+                                      - allowed-origins: origins in origin manager
+                                      - compute-groups: credentials for task requests
+                                      - config: entire worker.config
+                                      - <dot-path>: a property of worker.config
+      --kvin | --json                Use KVIN or JSON for show output
+      --startup-delay=num            Delay for num seconds during startup
+      --startup-delay-rnd=num        Delay for a random amount of time up to num seconds
+      --disable-httpd                Disable web interface (${httpd.getConfig().listen})
+      --register=key                 Use the given key to register this worker with your
+                                     Distributive portal account and exit
+      --unmanaged                    Do not report statistics to or read configuration
+                                     from scheduler; implies --no-claim-earnings
+      --no-claim-earnings            Do not transfer unclaimed earnings to the earnings
+                                     account when the worker starts
+      --claim-earnings=              Transfer unclaimed earnings to the specified
+                                     account and exit
+  -f, --pidfile=filename             Specify the location of the pid file
+      --no-pidfile                   Do not write the pid file
+  -v, --verbose                      Enable verbose output. Use more than once to
+                                     increase verbosity.
+`);
 }
-bannerLog.cumulative = [];
 
-function parseCliArgs()
+/**
+ * Generator which yields { option, optarg } represening the command-line options in the supplied argv.
+ *
+ * This program has long options that don't have a short option equivalent but posix-getopt doesn't
+ * support this, so we do a little bit of extra processing here. Each * in the optionsDefn becomes a
+ * unique character above \u1000 for the library to use, and then we disguise this fact from the user
+ * and any programmer not maintaining this function.
+ */
+function* parseCliOptions(argv)
 {
-  var defaultPidFileName;
-
-  defaultPidFileName = require('../lib/pidfile').getDefaultPidFileName(dcpConfig.worker.pidfile);
-
-  const cliArgs = require('dcp/cli')
-  .base('DCP Worker: Request work from the DCP Scheduler and send it to DCP Evaluators')
-    .options({
-      paymentAddress: {
-        describe: 'The address to deposit funds into, will use the default bank keystore if not provided.',
-        type: 'string',
-      },
-      cores: {
-        alias: 'c',
-        describe: 'Number of CPU and GPU cores to work with: the format is 7,1 (or just 7) for 7 CPU cores and 1 GPU',
-        type: 'string',
-      },
-      utilization: {
-        alias: 'u',
-        describe: 'default proportion of CPU,GPU to utilize: the format is -u 0.8,0.75 for 80% CPU and 75% GPU utilization',
-        type: 'string',
-      },
-      maxSandboxes: {
-        alias: 'm',
-        describe: 'Maximum number of sandboxes',
-        type: 'number',
-        default: undefined,
-      },
-      verbose: {
-        alias: 'v',
-        describe: 'Enable verbose output',
-        type: 'count',
-        default: false,
-        group: 'Output options',
-      },
-      outputMode: {
-        alias: ['o', 'output'],
-        describe: 'Set the output mode',
-        type: 'string',
-        default: 'detect',
-        choices: ['detect', 'console', 'dashboard', 'event-log', 'syslog', 'logfile'],
-        group: 'Output options',
-      },
-      hostname: {
-        alias: 'H',
-        describe: 'Evaluator hostname',
-        type: 'string',
-        default: dcpConfig.evaluator.location.hostname,
-      },
-      port: {
-        alias: 'p',
-        describe: 'Evaluator port',
-        type: 'number',
-        default: Number(dcpConfig.evaluator.location.port),
-      },
-      'job-id': {
-        alias: 'j',
-        hidden: true,
-        describe: 'Restrict worker to a specific job (use N times for N jobs)',
-        type: 'array',
-      },
-      join: {
-        alias: 'g',
-        hidden: true,
-        describe: 'Join compute group; the format is "joinKey,joinSecret" or "joinKey,eh1-joinHash"',
-        type: 'array'
-      },
-      joinKeystore: {
-        hidden: true,
-        /* future */
-      },
-
-      leavePublicGroup: {
-        type: 'boolean',
-        hidden: true,
-        describe: 'Do not fetch slices from global compute group.',
-        default: undefined,
-      },
-
-      publicGroupFallback: {
-        hidden: true,
-        describe: 'If set, worker will prefer private groups but fall back on the global group if no preferred work is available',
-        type: 'boolean',
-        default: undefined,
-        defaultDescription: undefined,
-      },
-
-      identityKey: {
-        hidden: true,
-        describe: 'Identity key, in hex format',
-        type: 'string',
-        group: 'Identity options',
-      },
-      identityKeystore: {
-        hidden: true,
-        describe: 'Identity keystore, in json format',
-        type: 'string',
-        group: 'Identity options',
-      },
-
-      reportInterval: {
-        describe: 'If set, output a status summary every [interval] seconds in console output mode',
-        type: 'number',
-        group: 'Output options',
-      },
-
-      showConfig: {
-        hide: false,
-        describe: 'Show worker config',
-        type: 'boolean',
-      },
-
-      logfile: {
-        describe: 'Path to log file',
-        type: 'string',
-        group: 'Log File output options',
-        default: path.resolve('../log/dcp-worker.log'),
-      },
-      syslogAddress: {
-        describe: 'Address of syslog server',
-        type: 'string',
-        group: 'Syslog output options',
-        default: 'loghost', // Unix standard for syslog
-      },
-      syslogFacility: {
-        describe: 'Name of syslog facility',
-        type: 'string',
-        group: 'Syslog output options',
-        default: 'local7',
-      },
-      syslogTransport: {
-        describe: 'Transport to connect to use for syslog',
-        type: 'string',
-        choices: ['udp','tcp','unix','tls'],
-        group: 'Syslog output options',
-        default: 'udp',
-      },
-      syslogPort: {
-        describe: 'UDP/TCP port to use for syslog',
-        type: 'number',
-        group: 'Syslog output options',
-        default: 514,
-      },
-
-      allowedOrigins: {
-        alias: 'a',
-        describe: 'modify the \'any\' allow origins of dcpConfig',
-        type: 'array'
-      },
-
-      watchdogInterval: {
-        alias: 'W',
-        describe: 'Number of milliseconds between watchdog cycles',
-        type: 'number',
-        hidden: true,
-      },
-      dumpConfig: {
-        describe: 'If set, dump the configuration and exit',
-        type: 'boolean',
-        hidden: true,
-      },
-      pidFile: {
-        alias: 'f',
-        describe: `create a .pid file for the worker; value overrides default location (${defaultPidFileName})`,
-        normalize: true
-      },
-    })
-  .strict()
-  .wrap(process.stdout.columns || 80)
-  .argv;
-
-  return cliArgs;
-}
+  const { BasicParser } = require('posix-getopt');
+  var parser;
+  var longOptCount = 0;
+  var optionsDefn = ''
+      + 'h(help)*:(earnings-account)*:(identity-keystore)'
+      + 'c:(cores)u:(utilization)m:(max-sandboxes)H:(hostname)p:(port)'
+      + 'o:(output)l:(logger)*:(logfile)*(overwrite-logfile)*:(syslog)*:(min-level)j:(job)g:(join)'
+      + 'a:(allow-origin)*(zero-trust)*(no-global)*(kvin)*(json)*:(show)*(unmanaged)'
+      + '*(no-claim-earnings)*:(register)*:(claim-earnings)*(reset)f:(pidfile)*(no-pidfile)v(verbose)';
+
+  optionsDefn = optionsDefn /* patchup long opt * to > \u1000 chars */
+    .match(/[A-Za-z*]:?(\([^)]*\))?/g)
+    .map(s => s[0] === '*' ? String.fromCharCode(++longOptCount + 0x1000) + s.slice(1) : s).join('');
+  const optionChars = optionsDefn.match(/[A-Za-z\u1000-\u1100/](:?\([^)]*\))?/g).map(s=>s[0]);
+  if (optionChars.length !== utils.uniq(optionChars).length)
+    throw new Error('getopt - option character used more than once');
+
+  const psw = process.stderr.write;
+  process.stderr.write = function patchupGetoptErrorOutput(s, ...args) {
+    /* posix-getopt library has useless chr for long opts when stderr.write('option requires an argument -- ' + chr + '\n'); */
+    if (s.startsWith('option requires an argument -- '))
+      s = `option ${argv[parser.optind() - 1]} requires an argument\n`;
+    psw.call(process.stderr, s, ...args);
+  };
+  parser = new BasicParser(optionsDefn, argv);
 
-// Imperfect, but handles CG { joinKey, joinHash }.
-function isHash(b) {
-  return b && b.length === 68 && b.startsWith('eh1-');
-}
+  for (let opthnd, lastOpt=2; (opthnd = parser.getopt()); lastOpt = parser.optind())
+  {
+    let option;
 
-/**
- * Replacement for process.exit() that tries to increase the probability
- * that remote log messages will make it out over the network.
-*/
-function processExit()
-{
-  logClosing('debug', 'Exit Code:', process.exitCode || 0);
-  if (console.close)
-    console.close();
-  setImmediate(() => {
-    process.exit.apply(null, arguments);
-  });
+    /* To fake long-only-opts, we use short opts >= \u1000), and present only the long opt below */
+    if (opthnd.option < '\u1000')
+      option = opthnd.option;
+    else
+      option = (Object.entries(parser.gop_aliases).filter(longShort => longShort[1] === opthnd.option)[0] || ['?'])[0];
+
+    yield { option, optarg: opthnd.optarg, argvSegment: argv.slice(lastOpt, parser.optind()) };
+    if (opthnd.error)
+      break;
+  }
+
+  process.stderr.write = psw; // eslint-disable-line require-atomic-updates
 }
 
 /**
- * Main program entry point. Assumes DCP client is already initialized and console logging is ready.
+ * Phase 1 options are options which MUST be parsed before the worker is instantiated or which affect
+ * the phase 2 options' operation. Unrecognized options are assumed to be phase 2 options.
+ * - evaluator location
+ * - logging details
+ * - console type
+ * - configuration data
+ *   - dcpConfig.worker
+ *   - program.argv
+ *
+ * Important - need to pay close attention to error/exit handling in phase1 because the log redirection
+ * and console capturing doesn't happen until afterwards.
+ *
+ * @param {Array}   argv            argument vector to process
+ * @param {object}  operatingMode   major settings for this application, can be mutated by this function
+ * @returns {object} with properties:
+ *                   - evaluatorOptions - options for setting up the evaluator
+ *                   - loggingOptions   - options for setting up the logger(s)
+ *                   - remainArgv       - arguments which were not processed (handled in phase 2)
  */
-async function main()
+function processCliOptsPhase1(argv, operatingMode)
 {
-  const wallet   = require('dcp/wallet');
-  const identity = require('dcp/identity');
-  const { DistributiveWorker } = require('dcp/worker');
-  var   workerConfig = {};
-  const cliArgs = parseCliArgs();
-  telnetd.setMainEval(function mainEval() { return eval(arguments[0]) }); // eslint-disable-line no-eval
-  require('../lib/startWorkerLogger').init(cliArgs); /* Start remote logger as early as possible */
-
-  /* Process any identity overrides and then establish our identity. */
-  identity.interactive = false;
-  if (cliArgs.identityKey || cliArgs.identityKeystore)
-    await identity.set(cliArgs.identityKey || cliArgs.identityKeystore);
-  await identity.login('$login');
-
-  /* Eagerly create a worker object and mutate its config property to reflect argv before starting it. */
-  const sawOptions = {
-    hostname: cliArgs.hostname,
-    port:     cliArgs.port
+  const loggingOptions = {
+    minLevel:    { all: undefined },  /* minimum logging levels for console and per logger */
+    loggers:     [],                  /* names of loggers (places logs go besides console) */
+    syslogUrl:   dcpConfig.worker.logging?.syslog?.url || new URL('udp://localhost:514/local7'),
+    logfile:     path.resolve(path.dirname(require.main.filename), dcpConfig.worker.logging?.logfile || '../log/dcp-worker.log'),
   };
-  if (typeof dcpConfig.worker.cleanupTimeout !== 'number')
-    dcpConfig.worker.cleanupTimeout = 60;
-  const SandboxConstructor = require('dcp-client/lib/standaloneWorker').workerFactory(sawOptions);
-
-  process.on('SIGINT',  handleSigDeath);
-  process.on('SIGTERM', handleSigDeath);
-  process.on('SIGQUIT', handleSigDeath);
-  process.on('unhandledRejection', handleUnhandled);
-  process.on('uncaughtException',  handleUnhandled);
-
-  if (cliArgs.paymentAddress)
-    workerConfig.paymentAddress = new wallet.Address(cliArgs.paymentAddress);
-  else if (typeof dcpConfig.worker.paymentAddress === 'string')
-    workerConfig.paymentAddress = new wallet.Address(workerConfig.paymentAddress);
-  else if (!workerConfig.paymentAddress)
-    workerConfig.paymentAddress = (await wallet.get({ oAuth: false })).address;
-
-  if (cliArgs.pidFile)
-    require('../lib/pidfile').write(cliArgs.pidFile);
-
-  if (cliArgs.leavePublicGroup !== undefined)
-    workerConfig.leavePublicGroup = mkBool(cliArgs.leavePublicGroup);
-  if (cliArgs.publicGroupFallback !== undefined)
-    workerConfig.publicGroupFallback = mkBool(cliArgs.publicGroupFallback);
-
-  /* Support magic value used by Windows screensaver configuration /wg June 2023 */
-  if (workerConfig.leavePublicGroup === 'fallback')
-  {
-    workerConfig.publicGroupFallback = true;
-    workerConfig.leavePublicGroup = undefined;
-  }
-
-  /* cliArgs.join is the list of compute groups to join */
-  if (cliArgs.join && cliArgs.join.length)
-  {
-    const cliComputeGroups = cliArgs.join
-      .map((el) => {
-        /* Map cliArgs.join to give us [{ joinKey, joinSecret/joinHash }...] */
-        const [a, b] = el.split(',');
-        return isHash(b) ? { joinKey: a, joinHash: b } : { joinKey: a, joinSecret: b };
-      })
-      .filter((el) => el.joinKey); /* Filter out entries with no joinKey */
-    workerConfig.computeGroups = cliComputeGroups;
-  }
+  const evaluatorOptions = {
+    hostname: dcpConfig.evaluator?.location?.hostname,
+    port:     dcpConfig.evaluator?.location?.hostname,
+  };
+  const remainArgv = argv.slice(0, 2);
 
-  if (cliArgs.jobId)
+  for (let { option, optarg, argvSegment } of parseCliOptions(argv))
   {
-    workerConfig.jobIds = [];
-    workerConfig.jobIds.push(...cliArgs.jobId);
+    switch(option)
+    {
+      case 'h':
+        usage(); /* needs primoridial console */
+        process.exit(exitCodes.normal);
+        break;
+      case 'zero-trust':
+        operatingMode.zeroTrust = true;
+        operatingMode.unmanaged = true;
+        break;
+      case 'unmanaged':
+        operatingMode.unmanaged = true;
+        break;
+      case 'H':
+        evaluatorOptions.hostname = optarg;
+        break;
+      case 'p':
+        evaluatorOptions.port = Number(optarg);
+        break;
+      case 'o':
+        if (optarg === 'console')
+          optarg = 'stdio'; /* undocumented back-compat synonym */
+        operatingMode.consoleType = optarg;
+        break;
+      case 'l':
+        loggingOptions.loggers.push(optarg);
+        break;
+      case 'syslog':
+        loggingOptions.loggers.push('syslog');
+        loggingOptions.syslogUrl = utils.makeSyslogUrl(loggingOptions.syslogUrl, optarg);
+        break;
+      case 'logfile':
+        loggingOptions.logfile = optarg;
+        loggingOptions.loggers.push('logfile');
+        break;
+      case 'overwrite-logfile':
+        loggingOptions.overwriteLogfile = true;
+        break;
+      case 'min-level':
+      {
+        if (optarg.indexOf(',') === -1)
+          optarg=`all,${optarg}`;
+        const [ which, level ] = optarg.split(',');
+        if (which !== 'all' && which !== 'console' && !loggers.exists(which))
+          reportUserError(`--min-level: ${which} is neither 'console' nor the name of a logger`);
+        if (!logLevels.lookup(level))
+          reportUserError(`--min-level: ${level} is not a valid log level (${Object.keys(logLevels).join(', ')})`);
+        loggingOptions.minLevel[which] = level;
+        break;
+      }
+      case 'kvin':
+        operatingMode.showSerializer = new (require('dcp/internal/kvin')).KVIN();
+        break;
+      case 'json':
+        operatingMode.showSerializer = JSON;
+        break;
+      case 'v':
+        loggingOptions.verbose++;
+        break;
+      case '?':
+        process.exit(exitCodes.error);
+        break;
+      case 'claim-earnings':
+      case 'register':
+        operatingMode.zeroTrust = true;
+        operatingMode.consoleType = 'stdio';
+        /* fallthrough */
+      default:
+        remainArgv.push.apply(remainArgv, argvSegment);
+        break;
+    }
   }
 
-  if (cliArgs.allowedOrigins)
-  {
-    workerConfig.allowOrigins = { any: [] };
-    workerConfig.allowOrigins.any.push(...cliArgs.allowedOrigins);
-  }
+  return { evaluatorOptions, loggingOptions, remainArgv };
+}
 
-  if (cliArgs.watchdogInterval)
-    workerConfig.watchdogInterval = cliArgs.watchdogInterval;
+async function processCliOptsPhase2(argv, operatingMode, loggingOptions)
+{
+  var pidfileName = dcpConfig.worker.pidfile || pidfile.getDefaultPidFileName();
 
-  if (cliArgs.dumpConfig)
+  for (let { option, optarg } of parseCliOptions(argv))
   {
-    console.log(JSON.stringify(require('dcp/dcp-config'), null, 2));
-    process.exit();
+    switch(option)
+    {
+      case 'earnings-account':
+        try
+        {
+          if (wallet.isAddress(optarg))
+            worker.config.paymentAddress = new wallet.Address(optarg);
+          else if (optarg[0] === '{')
+            worker.config.paymentAddress = (await new wallet.BankAccountKeystore(optarg)).address;
+          else
+          {
+            const { expandPath } = require('dcp/utils');
+            const json = fs.readFileSync(expandPath(optarg), 'utf8').trim();
+            worker.config.paymentAddress = (await new wallet.BankAccountKeystore(json)).address;
+          }
+        }
+        catch (error)
+        {
+          console.error(`invalid earnings account: '${optarg}'`);
+          await cleanupThenExit(exitCodes.error);
+        }
+        break;
+      case 'c':
+        Object.assign(worker.config.cores, parseResourceOption(optarg));
+        break;
+      case 'u':
+        Object.assign(worker.config.utilization, parseResourceOption(optarg));
+        break;
+      case 'm':
+        worker.config.maxSandboxes = Number(optarg);
+        break;
+      case 'j':
+        if (!worker.config.jobIds)
+          worker.config.jobIds = [];
+        worker.config.jobIds.push(optarg);
+        break;
+      case 'g':
+      {
+        const [joinKey, cred] = optarg.split(',');
+        const cg = { joinKey };
+        cg[utils.isHash(cred) ? 'joinHash' : 'joinSecret'] = cred;
+        worker.config.computeGroups[joinKey] = cg;
+        break;
+      }
+      case 'a':
+        worker.originManager.add(optarg, null, null);
+        break;
+      case 'no-global':
+        worker.config.leaveGlobalGroup = true;
+        break;
+      case 'show':
+        operatingMode.show = optarg;
+        break;
+      case 'startup-delay':
+        await a$sleep(Number(optarg));
+        break;
+      case 'startup-delay-rnd':
+        await a$sleep(Number(optarg) * Math.random());
+        break;
+      case 'f':
+        pidfileName = optarg;
+        break;
+      case 'no-pidfile':
+        pidfileName = false;
+        break;
+      case 'unmanaged':
+        worker.config.unmanaged = true;
+        break;
+      case 'no-claim-earnings':
+        worker.config.claimEarnings = false;
+        break;
+      case 'register':
+      {
+        if (!wallet.isPrivateKey(optarg))
+          await reportUserError('invalid registration key');
+        try
+        {
+          const reg = await worker.register(optarg);
+          if (reg instanceof Error)
+            console.error(reg);
+          else
+          {
+            if (reg.status !== 'registered')
+              console.error(`Registration failure: ${reg.status}`);
+            else
+            {
+              console.log(`Registration complete; worker ${worker.id} now managed by ${reg.owner}`);
+              if (pidfileName)
+                await require('../lib/pidfile').signal(pidfileName, 'SIGQUIT', 30, 'stopping worker on pid %i');
+            }
+          }
+        }
+        catch(error)
+        {
+          console.log('Registration failure:', error.message);
+          debug('dcp-worker:registration')(error);
+        }
+        await cleanupThenExit(exitCodes.normal);
+        break;
+      }
+      case 'claim-earnings':
+      {
+        if (!wallet.isAddress(optarg))
+          await reportUserError('invalid bank account');
+        const earningsAccount = new wallet.Address(optarg);
+        const res = await DistributiveWorker.transferUnclaimedEarnings(earningsAccount);
+        if (res.payload)
+          console.log(`Claimed ${res.payload} ⊇`);
+        else
+        {
+          debug('dcp-worker:transfer')(res.payload);
+          if (res.payload instanceof require('dcp/protocol').ErrorPayload)
+            console.error(res.payload.message);
+          else
+          {
+            const error = new Error(`error transferring unclaimed earnings to ${earningsAccount}`);
+            if (res.payload.code)
+              error.message += ` (${res.payload.code})`;
+            if (res.payload.stack)
+            {
+              error.stack = error.stack
+                + `\n    -------------------- [${dcpConfig.bank.services.bankTeller.location}]\n`
+                + res.payload.stack;
+            }
+            throw error;
+          }
+        }
+        await cleanupThenExit(exitCodes.normal);
+        break;
+      }
+      case 'disable-httpd':
+        operatingMode.startHttpd = false;
+        break;
+      default:
+        throw new Error(`unhandled option '${option}'`);
+      /* hidden / undocumented options below */
+      case 'slice-report-interval':
+        loggingOptions.sliceReportInterval = Number(optarg);
+        break;
+      case 'reset': /* can lose unclaimed earnings */
+        DistributiveWorker.resetLocalStorage();
+        console.info('reset complete');
+        await cleanupThenExit(exitCodes.normal);
+        break;
+    }
   }
 
-  worker = new DistributiveWorker(workerConfig, SandboxConstructor);
-  workerConfig = null; /* bug-finder */
-  processCoresAndMaxSandboxes(worker.config, cliArgs);
+  return { pidfileName };
+}
+
+/**
+ * Merge the configuration in the database for this program into the cli-derived options.
+ */
+async function mergeDbAppConfig(remainArgv, operatingMode, loggingOptions)
+{
+  const workerOpaqueId = DistributiveWorker.obtainWorkerId();
+  const db = await DistributiveWorker.jnuConnect();
 
-  if (cliArgs.showConfig)
+  const cursor = await db.select({ table: 'w$dcpWorkerAppConfig', prototype: { workerOpaqueId } });
+  const appConfig = await cursor.getFirst();
+  if (!appConfig)
   {
-    console.log(JSON.stringify(worker.config, null, 2));
-    process.exit();
+    if (loggingOptions.verbose)
+      console.log(' . no remote application config at', db.config.location.origin);
+    return;
   }
-
-  bannerLog(` * Starting Distributive Worker ${worker.id}`);
-  bannerLog(` . Using evaluator at ${dcpConfig.evaluator.location}`);
-  bannerLog(` . Configured for scheduler ${dcpConfig.scheduler.location}`);
-  bannerLog(` . Bank is ${dcpConfig.bank.location}`);
-  bannerLog(` . Earned funds will be deposited in account ${worker.config.paymentAddress}`);
-  bannerLog(` . Identity is ${identity.get()?.address}`);
-
-  worker.on('warning', (...payload) => console.warn (...payload));
-  worker.on('stop', () => { console.log('Worker is stopping') });
-  worker.on('end',  () => { logClosing('log', 'Worker has stopped') });
-  worker.on('job', job => console.log(` . Job: ${job.name} ${job.id.slice(0,8)} ${job.description || ''} ${job.link || ''}`));
-
-  // Display clean diagnostic when not debugging and env var
-  //   DCP_SUPERVISOR_DEBUG_DISPLAY_MAX_INFO isn't set.
-  worker.on('error',   (error) => {
-    if (displayMaxDiagInfo())
-      console.error(error);
+  if (loggingOptions.verbose)
+    console.log(' . loaded remote application config from', db.config.location.origin);
+
+  if (appConfig.syslogUrl)
+    remainArgv.unshift(`--syslog=${appConfig.syslogUrl}`);
+  if (appConfig.useSyslog)
+    remainArgv.unshift('--logger=syslog');
+  if (appConfig.useEventLog)
+    remainArgv.unshift('--logger=event-log');
+  if (appConfig.disableHttpd)
+    remainArgv.unshift('--disable-httpd');
+  if (appConfig.startupDelay)
+  {
+    if (appConfig.startupDelayType === 'rnd')
+      remainArgv.unshift(`--startup-delay-rnd=${appConfig.startupDelay}`);
     else
-    {
-      const errorCode = error.code ?? error.errorCode;
-      const location = error.stack.split('\n')[1].replace(/^\s*/,'');
-      let message = error.message;
+      remainArgv.unshift(`--startup-delay=${appConfig.startupDelay}`);
+  }
+}
 
-      if (errorCode)
-        message += ` (${error.code})`;
-      console.error(`Error: ${error.message} ${location}`);
-    }
-  });
-  require('../lib/default-ui-events').hook(worker, cliArgs);
+/**
+ * Main program entry point. Assumes DCP client is already initialized and console logging is ready.
+ */
+async function main()
+{
+  /* handle file-wide dcp-client imports */
+  identity = require('dcp/identity');
+  wallet   = require('dcp/wallet');
+  ({ a$sleep } = require('dcp/utils'));
+  ({ DistributiveWorker } = require('dcp/worker'));
+
+  const operatingMode = {
+    consoleType:    (!usingDebugger && process.stdout.isTTY) ? 'dashboard' : 'stdio', /* what kind of console? stdio, dashboard, none */
+    zeroTrust:      false, /* truey => do not load config data etc from scheduler */
+    showSerializer: false,
+    startHttpd:     true
+  };
 
-  if (cliArgs.outputMode === 'dashboard')
-    require('../lib/dashboard-tui').init(worker, cliArgs, bannerLog.cumulative);
+  identity.interactive = false;
+  process.exitCode = exitCodes.lostRef;
 
-  /* Let incorrect event-loop references keep us alive when linked with a debug library, but
-   * exit quickly/accurately for production code even when the library isn't perfect.
+  /* Telnetd is started ASAP to make it possible to troubleshoot very early problems. Then set our
+   * console type, initialize the loggers, and finally create a worker object and mutate its config to
+   * reflect argv before starting it.
    */
-  if (require('dcp/build').config.build !== 'debug')
-    worker.on('end', processExit);
-  else
-    worker.on('end', () => setTimeout(processExit, worker.config.cleanupTimeout * 1e3).unref());
+  telnetd.setMainEval(function mainEval() { return eval(arguments[0]) }); // eslint-disable-line no-eval
+  const {
+    remainArgv,         /* options not processed in phase1 - pick up in phase2 */
+    evaluatorOptions,   /* options for sandbox constructor factory */
+    loggingOptions,     /* options to tell us where logs go besides the console */
+  } = processCliOptsPhase1(process.argv, operatingMode);
+  await identity.login('$login');
 
-  if (worker.config.publicGroupFallback)
+  if (dcpConfig.worker.logging?.syslog)
+    loggingOptions.loggers.push('syslog');
+  if (dcpConfig.worker.logging?.logfile)
+    loggingOptions.loggers.push('logfile');
+  if (dcpConfig.worker.eventLog)
+    loggingOptions.loggers.push('event-log');
+  if (!operatingMode.unmanaged)
+    await mergeDbAppConfig(remainArgv, operatingMode, loggingOptions);
+  loggingOptions.loggers = utils.uniq(loggingOptions.loggers);
+  const newConsole = require('../lib/worker-consoles').setConsoleType(operatingMode.consoleType);
+  loggers.hook(newConsole, loggingOptions);
+
+  const SandboxConstructor = require('dcp-client/lib/standaloneWorker').workerFactory(evaluatorOptions);
+  worker = new DistributiveWorker(Object.assign({}, dcpConfig.worker, {
+    trustScheduler: operatingMode.zeroTrust ? false : dcpConfig.worker.trustScheduler,
+    unmanaged:      operatingMode.unmanaged ? true  : dcpConfig.worker.unmanaged,
+  }), SandboxConstructor);
+  const { pidfileName } = await processCliOptsPhase2(remainArgv, operatingMode, loggingOptions);
+  worker.runInfo.type = 'dcp-worker';
+
+  if (operatingMode.show)
   {
-    if (worker.config.leavePublicGroup)
-      console.warn(' ! Global Group fallback has been requested, but the global group is blocked by local configuration');
+    const output = await require('../lib/show').show(worker, operatingMode.show);
+    if (operatingMode.showSerializer)
+      console.log(operatingMode.showSerializer.stringify(output, null, 2));
     else
-    {
-      /* Enable global group fallback - this currently works by enabling or disabling the global group
-       * on the next fetch based on whether or not the most recent fetch was an empty task or not.
-       */
-      worker.on('fetch', fetchEventHandler);
-
-      function fetchEventHandler(ev)
-      {
-        if (ev instanceof Error)
-          console.error('Error fetching task:', ev);
-        else
-          worker.config.leavePublicGroup = Boolean(slicesFetched(ev) > 0);
-      }
-    }
+      console.log(output);
+    await cleanupThenExit(exitCodes.normal);
   }
 
-  /** @todo i18n */
-  function qty(amount, singular, plural)
-  {
-    if (Array.isArray(amount))
-      amount = amount.length;
-    if (!plural)
-      plural = singular + 's';
-    if (!amount)
-      return plural;
-    if (Number(amount) === 1)
-      return singular;
-    return plural;
-  }
+  const sandboxConfig = (new SandboxConstructor()).config;
+  console.info(` * Starting Distributive Worker ${worker.id}`);
+  console.info(` . Using evaluator at ${utils.shortLoc(sandboxConfig.location)}`);
+  console.info(` . Configured for scheduler ${dcpConfig.scheduler.location}`);
+  console.info(` . Bank is ${dcpConfig.bank.location}`);
+  if (worker.config.paymentAddress)
+    console.info(` . Earned funds will be deposited in account ${worker.config.paymentAddress}`);
+  else
+    console.info(' . Earned funds will be deposited into an unclaimed earnings account - register worker to claim');
+  console.info(` . Identity is ${identity.get()?.address}`);
+  if (operatingMode.zeroTrust)
+     console.info(' ! Zero Trust mode enabled');
+  else if (!worker.config.trustScheduler)
+    console.info(' ! Scheduler Trust disabled');
+
+  worker.on('warning', (...payload) => console.warn (...payload));
+  worker.on('stop', () => { console.log(' - Worker is stopping') });
+  worker.on('end',  () => { console.log(' * Worker has stopped') });
+  worker.on('job',   job    => console.log(` . Job: ${job.name} ${job.id.slice(0,8)} ${job.description || ''} ${job.link || ''}`));
+  worker.on('claim', amount => console.log(` . transfered ${amount} ⊇ to ${worker.config.paymentAddress}`));
+
+  require('../lib/default-ui-events').hook(worker, loggingOptions);
+  console.setWorker(worker);
 
   if (worker.config.jobIds?.length > 0)
-    bannerLog(` * Processing only ${qty(worker.config.jobIds, 'job')} ` + worker.config.jobIds.join(', '));
+    console.info(` * Processing only ${utils.qty(worker.config.jobIds, 'job')} ` + worker.config.jobIds.join(', '));
   if (worker.config.computeGroups && Object.keys(worker.config.computeGroups).length > 0)
-    bannerLog(` . Joining compute ${qty(worker.config.computeGroups, 'group')} ` + worker.config.computeGroups.map(el => el.joinKey).join(', '));
-  if (worker.config.publicGroupFallback)
-    bannerLog(' . Falling back on global group when preferred groups have no work');
-  if (worker.config.leavePublicGroup)
-    bannerLog(' . Leaving the global compute group');
-
-  bannerLog(` . Configured Cores: { cpu: ${worker.config.cores.cpu}, gpu: ${worker.config.cores.gpu} }`);
-  bannerLog(` . Utilization: { cpu: ${worker.config.utilization.cpu}, gpu: ${worker.config.utilization.gpu} }`);
-  bannerLog(` . Effective Cores: { cpu: ${worker.config.utilization.cpu * worker.config.cores.cpu}, gpu: ${worker.config.utilization.gpu * worker.config.cores.gpu} }`);
-  bannerLog(` . Maximum Sandboxes: ${worker.config.maxSandboxes}`);
-  if (cliArgs.verbose)
-    bannerLog(` + Verbosity level: ${cliArgs.verbose}`);
-  if (telnetd.hasOwnProperty('port'))
-    bannerLog(` ! telnetd listening on port ${telnetd.port}`);
-
-  let workerInfo;
-  console.throb('log', ` ! Waiting for dcp-evaluator on ${sawOptions.hostname}:${sawOptions.port} to start...`);
-  for (let i=0; !workerInfo; i++)
+    console.info(` . Joining compute ${utils.qty(worker.config.computeGroups, 'group')} ` + Object.values(worker.inspect.computeGroups).map(el => el.joinKey).join(', '));
+  if (worker.config.leaveGlobalGroup)
+    console.info(' ! Leaving the global compute group');
+
+  if (loggingOptions.verbose)
+    console.info(` + Verbosity level: ${loggingOptions.verbose}`);
+
+  if (operatingMode.startHttpd)
+    await httpd.a$init().catch(e => e);
+
+  /* Poll the evaluator forever until it accepts a connection */
+  let workerInfo = false;
+  console.throb(` . Waiting for dcp-evaluator on ${utils.shortLoc(sandboxConfig.location)} to start...`);
+  for (let i=0; workerInfo === false; i++)
   {
-    workerInfo = await require('../lib/worker-info').getEvaluatorInformation(sawOptions);
-    if (workerInfo)
+    const ts = performance.now();
+    if ((workerInfo = await require('../lib/worker-info').getEvaluatorInformation(sandboxConfig)))
       break;
-    console.throb();
+    if (performance.now() - ts > 100)
+      console.throb();
     await a$sleep(Math.max(i + 1, 10) / 4);
     console.throb();
   }
 
   if (Object.keys(workerInfo.worktimes).length > 0)
   {
-    bannerLog(' . Worktimes Available:');
+    console.info(' . Worktimes Available:');
     for (const wt of workerInfo.worktimes)
-      bannerLog(`    -\t${wt.name}@${wt.versions.join(';')}`);
+      console.info(`    - ${wt.name}@${wt.versions.join(';')}`);
   }
 
   if (!workerInfo.webgpu.enabled)
   {
-    bannerLog(' . WebGPU not enabled');
+    console.info(' . WebGPU not enabled');
     systemStateInfo.gpu = false;
   }
   else
   {
-    bannerLog(' . WebGPU available. GPU info:');
+    console.info(' . WebGPU available. GPU info:');
     for (let descriptor in workerInfo.webgpu.info)
-      bannerLog(`    -\t${descriptor}: ${workerInfo.webgpu.info[descriptor]}`);
+      console.info(`    - ${descriptor}: ${workerInfo.webgpu.info[descriptor]}`);
     systemStateInfo.gpu = Object.assign({}, workerInfo.webgpu.info);
-    for (let descriptor in worker.config.bannedGPUs)
+
+    /** @todo move bannedGPU support into DistributiveWorker class /wg jun 2025 */
+    const bannedGPUs = Array.isArray(worker.config.bannedGPUs) ? worker.config.bannedGPUs : [ worker.config.bannedGPUs ];
+    checkBans: for (let banEntry of bannedGPUs)
     {
-      if (worker.config.bannedGPUs[descriptor].test(workerInfo.webgpu.info[descriptor]))
+      for (let descriptor in banEntry)
       {
-        console.error(' * This GPU is not supported; disabling');
-        worker.config.cores = { cpu: worker.config.cores.cpu, gpu: 0 };
-        systemStateInfo.gpu.disabled = true;
-        break;
+        if (banEntry[descriptor].test(workerInfo.webgpu.info[descriptor]))
+        {
+          console.error(' * This GPU is not supported; disabling');
+          worker.config.cores = { cpu: worker.config.cores.cpu, gpu: 0 };
+          systemStateInfo.gpu.disabled = true;
+          break checkBans;
+        }
       }
     }
+
+    /** @todo move GPU type reporting into  DistributiveWorker class /wg jun 2025 */
+    worker.runInfo.gpuType = workerInfo.webgpu.info.device;
+    if (systemStateInfo.gpu.disabled)
+      worker.runInfo.gpuType += ' (disabled)';
   }
 
-  bannerLog(' . Supervisor version: ' + worker.supervisorVersion);
-  bannerLog(' . Output mode: ' + cliArgs.outputMode);
+  console.info(` . Utilization Target:  cpu: ${String(Math.round(worker.config.utilization.cpu * 100)).padStart(3, ' ')}% `
+            + `gpu: ${Math.round(worker.config.utilization.gpu * 100)}%`);
+  console.info(` . Configured Cores:    cpu: ${String(worker.config.cores.cpu).padEnd(3, ' ')} `
+            + ` gpu: ${worker.config.cores.gpu}`);
+  console.info(` . Maximum Sandboxes:  ${worker.config.maxSandboxes}`);
+  console.info(' . Supervisor version: ' + worker.supervisorVersion);
+  console.info(' . Console type:       ' + operatingMode.consoleType);
+  console.info(' . Logging:            ' + (loggingOptions.loggers.join(', ') || 'none'));
 
-  if (parseFloat(cliArgs.reportInterval))
-  {
-    if (cliArgs.outputMode !== 'dashboard')
-      setInterval(printReport, parseFloat(cliArgs.reportInterval) * 1000).unref();
-    else
-      console.warn('Ignoring --reportInterval in dashboard output mode');
-  }
+  if (loggingOptions.sliceReportInterval)
+    setInterval(() => reports.printSliceReport(worker), parseFloat(loggingOptions.sliceReportInterval) * 1000).unref();
 
   /* Start the worker. Normal process exit happens by virtue of the worker<end> event. Move forward one
-   * tick in case processExit was called during initialization.
+   * tick in case process.exit() was called during initialization. The dance with process.exitCode is so
+   * that we can detect when the process exited unexpectedly due to the loss of event loop references.
    */
-  setImmediate(async function workerStart() {
-    bannerLog(' * Ready.\n');
-    require('../lib/check-scheduler-version').check();
-    await worker.start();
+  if (handleSigDeath.count)
+    return;
+  require('../lib/check-scheduler-version').check();
+
+  worker.on('end', () => {
+    if (process.exitCode === exitCodes.lostRef)
+      process.exitCode = exitCodes.normal;
+    cleanupThenExit(exitCodes.normal);
   });
-}
-
-/**
- * Process the cores, utilization and maxSandboxes cli arguments.
- *
- * cliArgs.cores is the core count of the hardware to use.
- * It can be specified with only the cpu or gpu component, or both.
- *
- * E.g. -c 2,1  => cores = { cpu: 2,         gpu: 1 }
- *      -c 10   => cores = { cpu: 10,        gpu: <default> }
- *      -c ,10  => cores = { cpu: <default>, gpu: 10 }
- *      -u 0.80,0.75 => utilization = { cpu: 0.80, gpu: 0.75 }
- *      -m 5    => maxSandboxes = 5
- */
-function processCoresAndMaxSandboxes (workerConfig, cliArgs)
-{
-  if (typeof cliArgs['maxSandboxes'] !== 'undefined')
-    workerConfig.maxSandboxes = Number(cliArgs['maxSandboxes']);
 
-  const parseArg = (which) => {
-    if (cliArgs[which])
+  worker.on('error', function handleWorkerError(error) {
+    if (worker.isWorkerError && worker.isWorkerError(error))
     {
-      workerConfig[which] = {};
-      const [cpu, gpu] = cliArgs[which].split(',');
-      if (cpu?.length > 0)
-        workerConfig[which].cpu = Number(cpu);
-      if (gpu?.length > 0)
-        workerConfig[which].gpu = Number(gpu);
+      // A WorkerError is an error that has been vetted as safe for worker apps.
+      if (loggingOptions.verbose > 1)
+        console.error('Recoverable', error.code ? `${error.name} (${error.code}):` : `${error.name}:`, error.message);
+      else if (process.env.DCP_SUPERVISOR_DEBUG_DISPLAY_MAX_INFO)
+        console.error(error.code ? `${error.message};code=${error.code}` : `${error.message}`);
+      debug('dcp-worker:error')('Trapped DistributiveWorker<error>:', error);
+      return;
     }
-  };
+    /** @todo Errors from sandbox code need improvement /wg jun 2025 */
+    if (/^Received unhandled request from sandbox ring [0-9]. Data:/.exec(error.message))
+    {
+      const { ServerSideError } = require('dcp/utils');
+      const embeddedError = JSON.parse(error.message.slice(error.message.indexOf(' Data:') + 7)).error;
+      const ssError = new ServerSideError(embeddedError, dcpConfig.scheduler.location.href, 'dcp-worker');
+      error = ssError;
+    }
+    if (!handleWorkerError.count)
+    {
+      console.error('Unrecoverable', error.code ? `${error.name} (${error.code})` : error.name,
+                    '- shutting down the worker:', error.message);
+    }
+    worker.stop(Boolean(handleWorkerError.count));
+    handleWorkerError.count = 1 + (handleWorkerError.count || 0);
+  });
 
-  parseArg('utilization');
-  parseArg('cores');
+  if (pidfileName && require('../lib/pidfile').write(pidfileName) !== true)
+    await cleanupThenExit(exitCodes.pidConflict);
 
-  if (debugging())
+  if (worker.config.claimEarnings === false && !worker.config.unmanaged)
   {
-    console.debug(`dcp-worker: cores = { cpu: ${workerConfig.cores.cpu}, gpu: ${workerConfig.cores.gpu} }`);
-    console.debug('dcp-worker: utilization =',  workerConfig.utilization);
-    console.debug('dcp-worker: maxSandboxes =', workerConfig.maxSandboxes);
+    const amount = await DistributiveWorker.checkUnclaimedEarnings();
+    if (amount.gt(0))
+      console.note(` ! not claming earnings in the amount of ${amount} ⊇ (can claim later)`);
   }
-}
+
+  console.info(' * Ready.\n');
+  await worker.start();
+  httpd.setWorker(worker);
+} /* main() */
 
 /**
- * Log a closing message (or messages). Since the dashboard clears the screen on exit, we use the
- * memoized console property to log the message after we destroy the instance of screen.
+ * Parse a cpu,gpu resource option, eg for core count or utiliziation.
+ *
+ * @param {string}  option   argument to command-line option given by user. Spaces are ignored.
+ * @returns {object} with optional roperties cpu and gpu,
+ * @example
+ *  '2,1' => { cpu: 1, gpu: 1 }
+ *   ',1' => { gpu: 1 }
+ *  '2'   => { cpu: 2 }
+ *  '2,0' => { cpu: 2, gpu: 0 }
+ *  ''    => {}
  */
-function logClosing(facility, ...message)
+function parseResourceOption(option)
 {
-  var screen = require('../lib/worker-loggers/dashboard').screen;
-
-  if (screen)
-  {
-    /* Turn off fullscreen TUI and resume "normal" console logging.
-     * FUTURE: dashboard API should know how to unregister its hook so that we don't have to clobber
-     *         it here.
-     */
-
-    try
-    {
-      screen.log(...message);
-      screen.destroy();
-      screen = false;
-      console = new (require('console').Console)(process); // eslint-disable-line no-global-assign
-      telnetd.reintercept();
-    }
-    catch(error) {} // eslint-disable-line no-empty
-  }
-
-  console[facility](...message);
+  const [cpu, gpu] = option.replace(/ /g, '').split(',');
+  const res = {};
+  if (cpu?.length > 0)
+    res.cpu = Number(cpu);
+  if (gpu?.length > 0)
+    res.gpu = Number(gpu);
+  return res;
 }
 
 /**
@@ -584,110 +737,81 @@ function logClosing(facility, ...message)
  */
 function handleUnhandled(error)
 {
-  var _worker = worker;
-  worker = false;
-
-  process.exitCode = process.exitCode || EXIT_UNHANDLED;
-  logClosing('error', 'trapped unhandled', error);
-
-  if (_worker)
+  if (!error.request || !error.code?.startsWith('EHTTP_'))
+    console.error(' *** trapped unhandled', error);
+  else
   {
-    setTimeout(() => {
-      logClosing('error', 'handleFatalError timeout - exiting now');
-      processExit();
-    }, _worker.config.cleanupTimeout * 1e3).unref();
-    _worker.on('end', processExit);
-    _worker.stop();
+    console.error(' *** trapped unhandled XHR error', error.message);
+    /* appears to be from XHR via justFetch etc */
+    console.log(require('dcp/utils').justFetchPrettyError(error));
+    delete error.request;
+    delete error.response;
   }
 
+  process.off('unhandledRejection', handleUnhandled);
+  process.off('uncaughtException',  handleUnhandled);
+
   try
   {
-    let log = process.env.DCP_WORKER_UNHANDLED_REJECTION_LOG || worker?.config?.unhandledRejectionLog;
+    let log = process.env.DCP_WORKER_UNHANDLED_ERROR_LOG || worker?.config?.unhandledErrorLog;
     if (log)
-      fs.appendFileSync(process.env.DCP_WORKER_UNHANDLED_REJECTION_LOG,
+      fs.appendFileSync(process.env.DCP_WORKER_UNHANDLED_ERROR_LOG,
                         `${Date.now()}: ${error.message}\n${error.stack}\n\n`);
-  } catch(e) {} // eslint-disable-line no-empty
-}
+  } catch(e) {} // eslint-disable-line @distributive/brace-style,no-empty
 
-/** print the slice report via console.log */
-function printReport()
-{
-  console.log(sliceReport());
+  cleanupThenExit(exitCodes.unhandled);
 }
 
 /**
- *  Convert a timespan in ms to a human-readable interval in minutes and seconds
+ * Cause the process to exit ASAP, but take the time to gracefully unhook loggers so that log messages
+ * make it out. Gives up and exits forcefully after cleanupTimeout seconds.
  *
- *  @param  {number} el Milliseconds to convert
- *  @return {string}    Timespan formatted as `m:ss`
+ * @param {number} exitCode - the desired exit code of the dcp-worker process
+ * @returns {Promise} - a promise which never resolves, can be used to "block" execution of the current
+ *                      "thread" while the console and loggers are being unhooked.
  */
-function toInterval(el)
+function cleanupThenExit(exitCode)
 {
-  const m = Math.floor((el / 1000) / 60).toString(10);
-  const s = Math.floor((el / 1000) % 60).toString(10).padStart(2, '0');
-  return `${m}:${s}`;
-}
-
-/** retrieve a slice report screen */
-function sliceReport()
-{
-  let report = '';
-
-  report += ('='.repeat(78)) + '\n';
-
-  const sbStates = {
-    WORKING: 0,
-    ASSIGNED: 0,
-    READY: 0,
-    TERMINATED: 0,
-  };
-  const stateNames = {
-    WORKING: 'Working',
-    ASSIGNED: 'Assigned',
-    READY: 'Ready',
-    TERMINATED: 'Terminated',
-  };
-  worker.sandboxes.forEach(sb => {
-    const { state } = sb;
-    if (!sbStates[state])
-      sbStates[state] = 0;
-    sbStates[state]++;
-  });
+  debug('dcp-worker:exit')('cleanup and exit, code', exitCode);
+  if (cleanupThenExit.busy)
+  {
+    if (!process.exitCode)
+      process.exitCode = exitCode;
+    debug('dcp-worker:exit')('exit race, bailing on cleanup for exit code', exitCode);
+    return;
+  }
 
-  report += (Date()) + '\n';
-  report += ('Sandboxes:') + '\n';
-  Object.keys(sbStates).forEach(state => {
-    const stateName = stateNames[state] || state;
-    report += (`  ${(stateName + ':').padEnd(12)} ${sbStates[state]}`) + '\n';
-  })
-  report += (`  * ALL:       ${worker.sandboxes.length}`) + '\n';
-
-  report += ('Progress:') + '\n';
-  worker.workingSandboxes.forEach(sb => {
-    const jobName = sb.job?.public?.name || `idek (${sb.jobId})`;
-    let el = Date.now() - sb.sliceStartTime;
-    const t = el < 1000000
-          ? toInterval(el)
-          : 'new';
-
-    el = sb.progressReports && sb.progressReports.last
-      ? Date.now() - (sb.sliceStartTime + (sb.progressReports.last?.timestamp ?? 0))
-      : 0;
-    const pct = (typeof sb.progress) === 'number'
-          ? `${Number(sb.progress).toFixed(0).padStart(2)}%`
-          : 'ind';
-    const stale = (el < 2000) ? '' : `(stale: ${toInterval(el)})`;
-
-    report += (` ${String(sb.id).padStart(4)}: ${sb.jobId} ${jobName.padEnd(34)} `+ `${t} ${pct} ${stale}`.padStart(13)) + '\n';
-  });
+  worker = false;
+  cleanupThenExit.busy = true;
+  process.exitCode = exitCode;
 
-  report += ('Slices:') + '\n';
-  report += (`  working:     ${worker.workingSlices.length}`) + '\n';
-  report += (`  queued:      ${worker.queuedSlices.length}`) + '\n';
+  /* Final event loop reference; keeps the process alive while the loggers unhook */
+  setTimeout(() => {
+    console.warn(' *** logger cleanup timeout expired ***');
+    process.exit();
+  }, 10 * 1e3).ref();
 
-  report += ('='.repeat(78)) + '\n';
+  try
+  {
+    process.off('SIGESC',  handleSigDeath);
+    process.off('SIGINT',  handleSigDeath);
+    process.off('SIGTERM', handleSigDeath);
+    process.off('SIGQUIT', handleSigDeath);
+    process.off('unhandledRejection', handleUnhandled);
+    process.off('uncaughtException',  handleUnhandled);
+    if (console.close)
+      console.close();
+    loggers.unhook()
+      .catch(error => { console.error('Error unhooking loggers:', error) })
+      .finally(() => process.exit());
+  }
+  catch(error)
+  {
+    console.error('Cleanup error:', error);
+    process.exit(exitCodes.unhandled);
+  }
 
-  return report;
+  return new Promise(()=>1);
 }
 
 /**
@@ -696,53 +820,49 @@ function sliceReport()
  *  - unregistering the signal handler and replacing it with a call to process.exit() after
  *    two tries.
  *    -> this allows a third signal to forcibly terminate the process
- *  - set a long timeout (dcpConfig.worker.cleanupTimeout seconds), after which the process
- *    exits forcibly with a non-zero exit code (unix standard for various signals)
+ *  - set a long timeout (cleanupTimeout seconds), after which the process exits forcibly with a
+ *    non-zero exit code (unix standard for various signals)
  *  - the worker is soft-stopped after the first signal if it is not SIGQUIT but hard stopped
  *    all other times.
  */
-function handleSigDeath(signalName, signal)
+async function handleSigDeath(signalName, signal)
 {
+  const exitCode = signal ? signal - 128 /* unix standard */ : exitCodes.normal;
   handleSigDeath.count = Number(handleSigDeath.count || 0) + 1;
-
   if (handleSigDeath.count > 2)
   {
     process.on(signalName, () => {
       console.error(signalName);
-      process.exit(signal - 128)
+      cleanupThenExit(exitCode);
     });
   }
 
-  if (!worker)
+  const warning = signal
+        ? `\ntrapped ${signalName}, signal ${signal}`
+        : `\ntrapped ${signalName === 'SIGESC' ? '<esc>' : signalName}`;
+  if (!worker || !worker.workingSandboxes.length)
   {
-    console.warn(`trapped ${signalName}, signal ${signal}`);
-    die();
+    console.warn(warning);
+    await cleanupThenExit(exitCode);
+    return;
   }
   else
   {
     const immediate = signalName === 'SIGQUIT' || handleSigDeath.count > 1;
-    console.warn(`trapped ${signalName}, signal ${signal} -- stopping worker`,
-                 immediate ? 'immediately' : `after ${handleSigDeath.count} slices have finished`);
-    worker.stop(immediate);
-    setTimeout(die, worker.config.cleanupTimeout * 1e3).unref();
-  }
-  process.emit('dcpBeforeExit');
-
-  function die()
-  {
-    processExit(signal - 128);
+    console.warn(`${warning} -- stopping worker`,
+                 immediate
+                 ? 'immediately'
+                 : `after ${worker.workingSandboxes.length} slices have finished`);
+    worker.stop(immediate); /* DistributiveWorker<end> triggers cleanupThenExit */
+    worker.removeAllListeners('warning');
   }
 
   if (handleSigDeath.count === 3)
-    die();
+    await cleanupThenExit(exitCode);
 }
-globalThis.die = () => handleSigDeath('QUIT', 15);
 
-/**
- * Cast b to boolean such that 'false' becomes false, falsey things become false, and everything else
- * becomes true.
- */
-function mkBool(b)
+function reportUserError(message)
 {
-  return Boolean(b) && (b !== 'false');
+  console.error(message);
+  return cleanupThenExit(exitCodes.userError);
 }