@logicseek/hello-cc 0.1.9 → 1.0.1

package/lib/shared/file-lock.mjs

@@ -0,0 +1,377 @@
+import { createHash } from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+import { Worker } from 'node:worker_threads';
+import { aggregateCleanupFailure } from './cleanup-error.mjs';
+
+const NO_ERROR = Symbol('no-file-lock-error');
+const STATE_INDEX = 0;
+const DETAIL_INDEX = 1;
+const STATE = Object.freeze({
+  STARTING: 0,
+  ACQUIRED: 1,
+  BUSY: 2,
+  TIMEOUT: 3,
+  FAILED: 4,
+  RELEASED: 5,
+  RELEASE_FAILED: 6
+});
+const HOST = '127.0.0.1';
+const PORT_BASE = 20_000;
+const PORT_COUNT = 40_000;
+const PORT_CANDIDATE_COUNT = 4;
+const STARTUP_GRACE_MS = 5000;
+const RELEASE_GRACE_MS = 5000;
+const WORKER_URL = new URL('./socket-lock-worker.mjs', import.meta.url);
+const WORKER_BOOTSTRAP = String.raw`
+  import('node:worker_threads').then(({ parentPort, workerData }) => {
+    const state = new Int32Array(workerData.stateBuffer);
+    const fail = () => {
+      Atomics.store(state, 1, 1);
+      Atomics.store(state, 0, workerData.states.FAILED);
+      Atomics.notify(state, 0);
+      parentPort.close();
+    };
+    import(workerData.moduleUrl).then((module) => {
+      if (typeof module.runSocketLockWorker !== 'function') throw new TypeError('invalid worker module');
+      module.runSocketLockWorker(workerData);
+    }).catch(fail);
+  }).catch(() => {});
+`;
+
+function sameObject(left, right) {
+  return left?.dev === right?.dev && left?.ino === right?.ino;
+}
+
+function invalidLock(message, cause = null) {
+  const error = new Error(message, cause ? { cause } : undefined);
+  error.code = 'ERR_INVALID_FILE_LOCK';
+  return error;
+}
+
+function busyError(key) {
+  const error = new Error(`file lock is busy: ${key}`);
+  error.code = 'ERR_FILE_LOCK_BUSY';
+  return error;
+}
+
+function timeoutError(key) {
+  const error = new Error(`timed out waiting for file lock: ${key}`);
+  error.code = 'ERR_FILE_LOCK_TIMEOUT';
+  return error;
+}
+
+function workerError(key, phase, cause = null) {
+  const error = new Error(
+    `file lock worker ${phase} failed: ${key}`,
+    cause ? { cause } : undefined
+  );
+  error.code = phase === 'release'
+    ? 'ERR_FILE_LOCK_RELEASE_FAILED'
+    : 'ERR_FILE_LOCK_WORKER_START_FAILED';
+  return error;
+}
+
+function startupTimeoutError(key) {
+  const error = new Error(`file lock worker did not start in time: ${key}`);
+  error.code = 'ERR_FILE_LOCK_WORKER_START_TIMEOUT';
+  return error;
+}
+
+function canonicalTarget(value, { createParent = true } = {}) {
+  if (typeof value !== 'string' || value.length === 0) {
+    throw new TypeError('file lock target must be a non-empty path');
+  }
+  const supplied = path.resolve(value);
+  const suppliedParent = path.dirname(supplied);
+  if (createParent) fs.mkdirSync(suppliedParent, { recursive: true, mode: 0o700 });
+  const canonicalParent = fs.realpathSync.native(suppliedParent);
+  const parentIdentity = fs.statSync(canonicalParent);
+  if (!parentIdentity.isDirectory()) {
+    throw invalidLock(`file lock parent is not a directory: ${suppliedParent}`);
+  }
+  const canonicalKey = path.join(canonicalParent, path.basename(supplied));
+  return {
+    suppliedKey: supplied,
+    suppliedParent,
+    canonicalParent,
+    canonicalTarget: canonicalKey,
+    parentIdentity,
+    key: canonicalKey
+  };
+}
+
+function assertStableParent(location) {
+  const canonicalParent = fs.realpathSync.native(location.suppliedParent);
+  const parentIdentity = fs.statSync(canonicalParent);
+  if (canonicalParent !== location.canonicalParent ||
+      !sameObject(parentIdentity, location.parentIdentity) ||
+      !parentIdentity.isDirectory()) {
+    throw invalidLock('file lock parent changed during acquisition');
+  }
+}
+
+function endpointForLocation(location) {
+  return endpointForKey(location.key);
+}
+
+function endpointForKey(key) {
+  const digest = createHash('sha256').update(key).digest();
+  return {
+    host: HOST,
+    port: PORT_BASE + digest.readUInt32BE(0) % PORT_COUNT,
+    key
+  };
+}
+
+function candidatePortsForKey(key) {
+  const ports = [];
+  for (let index = 0; ports.length < PORT_CANDIDATE_COUNT; index += 1) {
+    const digest = index === 0
+      ? createHash('sha256').update(key).digest()
+      : createHash('sha256').update(`hcc-file-lock-port-v1\0${index}\0${key}`).digest();
+    const port = PORT_BASE + digest.readUInt32BE(0) % PORT_COUNT;
+    if (!ports.includes(port)) ports.push(port);
+  }
+  return ports;
+}
+
+function lockIdentityForKey(key) {
+  return createHash('sha256').update(`hcc-file-lock-v1\0${key}`).digest('hex');
+}
+
+function lockTargetsForLocation(location) {
+  return [...new Set([location.suppliedKey, location.key])]
+    .sort()
+    .map((key) => ({
+      identity: lockIdentityForKey(key),
+      ports: candidatePortsForKey(key)
+    }));
+}
+
+function endpointsForLocation(location) {
+  const byPort = new Map();
+  for (const key of [location.suppliedKey, location.key].sort()) {
+    const endpoint = endpointForKey(key);
+    if (!byPort.has(endpoint.port)) byPort.set(endpoint.port, endpoint);
+  }
+  return [...byPort.values()].sort((left, right) => left.port - right.port);
+}
+
+// The primary endpoint remains stable for diagnostics. Acquisition uses
+// additional deterministic candidates plus an identity handshake so an
+// unrelated local listener cannot impersonate this target's lock.
+export function fileLockEndpoint(target) {
+  const location = canonicalTarget(target);
+  assertStableParent(location);
+  return endpointForLocation(location);
+}
+
+export function fileLockEndpoints(target) {
+  const location = canonicalTarget(target);
+  assertStableParent(location);
+  return endpointsForLocation(location);
+}
+
+function combineCleanup(primary, cleanup, message, phase, key) {
+  if (primary === NO_ERROR) return cleanup;
+  return aggregateCleanupFailure(primary, cleanup, message, { phase, lockPath: key });
+}
+
+function defaultWorkerFactory({ workerSource, workerData }) {
+  // The eval bootstrap owns module-load failures and reports them through the
+  // shared state before closing its parent port. No parent execArgv is needed.
+  return new Worker(workerSource, { eval: true, workerData, execArgv: [] });
+}
+
+function injectedFailure(worker, state, phase, key) {
+  const detail = Atomics.load(state, DETAIL_INDEX);
+  try {
+    const failure = worker?.failure?.(detail, phase);
+    if (failure) return failure;
+  } catch (error) {
+    return workerError(key, phase, error);
+  }
+  return workerError(key, phase);
+}
+
+function terminateWorker(worker, primary, key) {
+  if (!worker) return primary;
+  try {
+    const pending = worker.terminate();
+    if (pending && typeof pending.then === 'function') {
+      pending.catch(() => {});
+      const cleanup = new Error(`file lock worker termination is unconfirmed: ${key}`);
+      cleanup.code = 'ERR_FILE_LOCK_WORKER_TERMINATION_UNCONFIRMED';
+      return combineCleanup(
+        primary,
+        cleanup,
+        'file lock operation failed and asynchronous worker termination cannot be confirmed',
+        'terminate',
+        key
+      );
+    }
+    return primary;
+  } catch (cleanup) {
+    return combineCleanup(
+      primary,
+      cleanup,
+      'file lock operation and worker termination both failed',
+      'terminate',
+      key
+    );
+  }
+}
+
+function acquisitionError(status, resources) {
+  if (status === STATE.BUSY) return busyError(resources.location.key);
+  if (status === STATE.TIMEOUT) return timeoutError(resources.location.key);
+  if (status === STATE.FAILED) {
+    return injectedFailure(resources.worker, resources.state, 'startup', resources.location.key);
+  }
+  return startupTimeoutError(resources.location.key);
+}
+
+function acquireWorker(location, options, workerFactory) {
+  const buffer = new SharedArrayBuffer(Int32Array.BYTES_PER_ELEMENT * 2);
+  const state = new Int32Array(buffer);
+  const endpoints = endpointsForLocation(location);
+  const targets = lockTargetsForLocation(location);
+  const resources = { location, endpoints, state, worker: null };
+  let primary = NO_ERROR;
+  try {
+    resources.worker = workerFactory({
+      workerSource: WORKER_BOOTSTRAP,
+      workerUrl: WORKER_URL,
+      workerData: {
+        stateBuffer: buffer,
+        states: STATE,
+        targets,
+        moduleUrl: WORKER_URL.href,
+        timeoutMs: options.timeoutMs,
+        retryMs: options.retryMs,
+        nonblocking: options.nonblocking
+      },
+      state,
+      states: STATE
+    });
+    if (!resources.worker || typeof resources.worker.unref !== 'function' ||
+        typeof resources.worker.postMessage !== 'function' ||
+        typeof resources.worker.terminate !== 'function') {
+      throw new TypeError('file lock worker factory returned an invalid worker');
+    }
+    if (typeof resources.worker.on === 'function') {
+      // A module-load failure happens before the Worker can publish FAILED.
+      // Suppress the otherwise-unhandled event; the bounded startup wait below
+      // converts this path to ERR_FILE_LOCK_WORKER_START_TIMEOUT.
+      resources.worker.on('error', () => {});
+    }
+    resources.worker.unref();
+    const waitMs = STARTUP_GRACE_MS +
+      (options.nonblocking ? 0 : Math.ceil(options.timeoutMs)) + 100;
+    Atomics.wait(state, STATE_INDEX, STATE.STARTING, waitMs);
+    const status = Atomics.load(state, STATE_INDEX);
+    if (status !== STATE.ACQUIRED) throw acquisitionError(status, resources);
+    assertStableParent(location);
+    return resources;
+  } catch (error) {
+    primary = error;
+  }
+  if (Atomics.load(state, STATE_INDEX) === STATE.ACQUIRED) {
+    throw releaseWorker(resources, primary);
+  }
+  if ([STATE.BUSY, STATE.TIMEOUT, STATE.FAILED].includes(
+    Atomics.load(state, STATE_INDEX)
+  )) {
+    throw primary;
+  }
+  throw terminateWorker(resources.worker, primary, location.key);
+}
+
+function releaseWorker(resources, primary) {
+  let error = primary;
+  let mustTerminate = false;
+  try {
+    resources.worker.postMessage({ type: 'release' });
+    Atomics.wait(resources.state, STATE_INDEX, STATE.ACQUIRED, RELEASE_GRACE_MS);
+    const status = Atomics.load(resources.state, STATE_INDEX);
+    if (status !== STATE.RELEASED) {
+      const cleanup = status === STATE.RELEASE_FAILED
+        ? injectedFailure(resources.worker, resources.state, 'release', resources.location.key)
+        : workerError(resources.location.key, 'release');
+      mustTerminate = status !== STATE.FAILED;
+      error = combineCleanup(
+        error,
+        cleanup,
+        'file lock operation and worker release both failed',
+        'release',
+        resources.location.key
+      );
+    }
+  } catch (cleanup) {
+    mustTerminate = true;
+    error = combineCleanup(
+      error,
+      cleanup,
+      'file lock operation and worker release both failed',
+      'release',
+      resources.location.key
+    );
+  }
+  return mustTerminate
+    ? terminateWorker(resources.worker, error, resources.location.key)
+    : error;
+}
+
+export function createFileLock({ workerFactory = defaultWorkerFactory } = {}) {
+  if (typeof workerFactory !== 'function') {
+    throw new TypeError('file lock workerFactory must be a function');
+  }
+  return function withConfiguredFileLock(
+    target,
+    fn,
+    options = {}
+  ) {
+    const timeoutMs = options.timeoutMs === undefined ? 5000 : options.timeoutMs;
+    const retryMs = options.retryMs === undefined ? 25 : options.retryMs;
+    const nonblocking = options.nonblocking === undefined ? false : options.nonblocking;
+    const createParent = options.createParent === undefined ? true : options.createParent;
+    if (typeof fn !== 'function') throw new TypeError('file lock callback must be a function');
+    if (!Number.isFinite(timeoutMs) || timeoutMs < 0) {
+      throw new RangeError('file lock timeoutMs must be a non-negative finite number');
+    }
+    if (!Number.isFinite(retryMs) || retryMs <= 0) {
+      throw new RangeError('file lock retryMs must be a positive finite number');
+    }
+    if (typeof nonblocking !== 'boolean') {
+      throw new TypeError('file lock nonblocking must be a boolean');
+    }
+    if (typeof createParent !== 'boolean') {
+      throw new TypeError('file lock createParent must be a boolean');
+    }
+    if (fn.constructor?.name === 'AsyncFunction') {
+      throw new TypeError('withFileLock requires a synchronous callback');
+    }
+
+    const location = canonicalTarget(target, { createParent });
+    const resources = acquireWorker(location, { timeoutMs, retryMs, nonblocking }, workerFactory);
+    let result;
+    let primary = NO_ERROR;
+    try {
+      // Protected I/O must use this fixed path. The supplied parent alias may
+      // be retargeted after acquisition and belongs to a different lock domain.
+      result = fn(location.canonicalTarget);
+      if (result && typeof result.then === 'function') {
+        Promise.resolve(result).catch(() => {});
+        throw new TypeError('withFileLock requires a synchronous callback');
+      }
+    } catch (error) {
+      primary = error;
+    }
+    const finalError = releaseWorker(resources, primary);
+    if (finalError !== NO_ERROR) throw finalError;
+    return result;
+  };
+}
+
+export const withFileLock = createFileLock();

package/lib/shared/json-file.mjs

@@ -6,9 +6,13 @@ export function readJsonSafe(filePath) {
   catch { return null; }
 }
 
-export function writeJsonSafe(filePath, data) {
+export function writeJsonSafe(filePath, data, opts = {}) {
   fs.mkdirSync(path.dirname(filePath), { recursive: true });
   const tmpPath = filePath + '.tmp.' + process.pid;
-  fs.writeFileSync(tmpPath, JSON.stringify(data, null, 2) + '\n');
+  const writeOpts = opts.mode !== undefined ? { mode: opts.mode } : undefined;
+  fs.writeFileSync(tmpPath, JSON.stringify(data, null, 2) + '\n', writeOpts);
   fs.renameSync(tmpPath, filePath);
+  if (opts.mode !== undefined) {
+    try { fs.chmodSync(filePath, opts.mode); } catch {}
+  }
 }

package/lib/shared/redact.mjs

@@ -0,0 +1,60 @@
+const REDACTED = '[REDACTED]';
+const CIRCULAR = '[Circular]';
+
+function isSecretKey(key) {
+  const normalized = String(key || '').toLowerCase().replace(/[^a-z0-9]/g, '');
+  return normalized === 'authorization' ||
+    normalized === 'cookie' ||
+    normalized === 'setcookie' ||
+    normalized.includes('secret') ||
+    normalized.endsWith('password') ||
+    normalized.endsWith('credential') ||
+    normalized.endsWith('credentials') ||
+    normalized.endsWith('apikey') ||
+    normalized.endsWith('privatekey') ||
+    normalized.endsWith('token');
+}
+
+function redactString(value) {
+  return String(value)
+    .replace(/\b(?:cookie|set-cookie)\s*:\s*[^\r\n]*/gi, (header) => `${header.split(':', 1)[0]}: ${REDACTED}`)
+    .replace(/\bBearer\s+[^\s,;]+/gi, `Bearer ${REDACTED}`)
+    .replace(/(--token(?:=|\s+))(?:"[^"]*"|'[^']*'|[^\s]+)/gi, `$1${REDACTED}`)
+    .replace(/([?&](?:token|access_token|api_key)=)[^&#\s]*/gi, `$1${REDACTED}`)
+    .replace(/(hcc_sid=)[^;\s]*/gi, `$1${REDACTED}`);
+}
+
+export function redactCliArgs(args) {
+  const values = Array.from(args || [], (entry) => String(entry));
+  return values.map((entry, index) => {
+    if (index > 0 && values[index - 1] === '--token') return REDACTED;
+    if (entry.startsWith('--token=')) return `--token=${REDACTED}`;
+    return redactString(entry);
+  });
+}
+
+export function redactSecrets(value, seen = new WeakSet()) {
+  if (typeof value === 'string') return redactString(value);
+  if (value === null || typeof value !== 'object') return value;
+  if (seen.has(value)) return CIRCULAR;
+  seen.add(value);
+
+  try {
+    if (value instanceof Error) {
+      return {
+        name: value.name,
+        message: redactString(value.message || ''),
+        stack: redactString(value.stack || '')
+      };
+    }
+    if (Array.isArray(value)) return value.map((entry) => redactSecrets(entry, seen));
+
+    const clone = {};
+    for (const [key, entry] of Object.entries(value)) {
+      clone[key] = isSecretKey(key) ? REDACTED : redactSecrets(entry, seen);
+    }
+    return clone;
+  } finally {
+    seen.delete(value);
+  }
+}

package/lib/shared/socket-lock-worker.mjs

@@ -0,0 +1,250 @@
+import net from 'node:net';
+import { parentPort } from 'node:worker_threads';
+
+const STATE_INDEX = 0;
+const DETAIL_INDEX = 1;
+const PROTOCOL_PREFIX = 'HCC_FILE_LOCK_V1 ';
+const PROBE_TIMEOUT_MS = 25;
+
+export function runSocketLockWorker(workerData) {
+  const state = new Int32Array(workerData.stateBuffer);
+  const states = workerData.states;
+  const targets = workerData.targets;
+  const acceptedSockets = new Set();
+  let servers = [];
+  let closeOperation = null;
+  let contentionDeadline = null;
+  let releasing = false;
+  let terminalFailureRequested = false;
+  let finished = false;
+  let generation = 0;
+
+  function publish(status, detail = 0) {
+    Atomics.store(state, DETAIL_INDEX, detail);
+    Atomics.store(state, STATE_INDEX, status);
+    Atomics.notify(state, STATE_INDEX);
+  }
+
+  function finish(status, detail = 0) {
+    if (finished) return;
+    if (terminalFailureRequested) {
+      status = states.FAILED;
+      detail = 1;
+    }
+    finished = true;
+    publish(status, detail);
+    parentPort.close();
+  }
+
+  function closeServers(callback) {
+    if (closeOperation !== null) {
+      closeOperation.callbacks.push(callback);
+      if (closeOperation.cleanupStarted) destroyAcceptedSockets();
+      return;
+    }
+    const closing = servers;
+    servers = [];
+    const operation = {
+      callbacks: [callback],
+      cleanupStarted: false,
+      closing,
+      completed: false,
+      firstError: null,
+      remaining: closing.length
+    };
+    closeOperation = operation;
+    const complete = () => {
+      if (operation.completed || !operation.cleanupStarted || operation.remaining !== 0) return;
+      operation.completed = true;
+      closeOperation = null;
+      const callbacks = operation.callbacks;
+      operation.callbacks = [];
+      operation.closing = [];
+      for (const waiting of callbacks) waiting(operation.firstError);
+    };
+    const closed = (error = null) => {
+      if (error && !operation.firstError) operation.firstError = error;
+      operation.remaining -= 1;
+      complete();
+    };
+    for (const server of operation.closing) {
+      let settled = false;
+      const serverClosed = (error = null) => {
+        if (settled) return;
+        settled = true;
+        closed(error);
+      };
+      try {
+        server.close(serverClosed);
+      } catch (error) {
+        serverClosed(error);
+      }
+    }
+    destroyAcceptedSockets();
+    operation.cleanupStarted = true;
+    complete();
+  }
+
+  function requestTerminalFailure() {
+    if (finished) return;
+    terminalFailureRequested = true;
+    generation += 1;
+    closeServers(() => finish(states.FAILED, 1));
+  }
+
+  function retryAfterContention() {
+    if (workerData.nonblocking) {
+      finish(states.BUSY);
+      return;
+    }
+    if (contentionDeadline === null) {
+      contentionDeadline = performance.now() + workerData.timeoutMs;
+    }
+    const remaining = contentionDeadline - performance.now();
+    if (remaining <= 0) {
+      finish(states.TIMEOUT);
+      return;
+    }
+    setTimeout(attemptAll, Math.min(workerData.retryMs, remaining));
+  }
+
+  function retryCleanly(attemptGeneration) {
+    if (finished || attemptGeneration !== generation) return;
+    generation += 1;
+    closeServers((error) => {
+      if (error) requestTerminalFailure();
+      else if (!terminalFailureRequested) retryAfterContention();
+    });
+  }
+
+  function lockBanner(identity) {
+    return `${PROTOCOL_PREFIX}${identity}\n`;
+  }
+
+  function serveLock(socket, identity) {
+    acceptedSockets.add(socket);
+    socket.once('close', () => acceptedSockets.delete(socket));
+    socket.on('error', () => {});
+    socket.end(lockBanner(identity));
+  }
+
+  function destroyAcceptedSockets() {
+    for (const socket of acceptedSockets) {
+      try { socket.destroy(); } catch {}
+    }
+  }
+
+  function probeOccupant(port, identity, callback) {
+    const expected = lockBanner(identity);
+    let received = '';
+    let settled = false;
+    let socket;
+    const settle = (matching) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      try { socket?.destroy(); } catch {}
+      callback(matching);
+    };
+    const timer = setTimeout(() => settle(false), PROBE_TIMEOUT_MS);
+    try {
+      socket = net.createConnection({ host: '127.0.0.1', port });
+      socket.setEncoding('utf8');
+      socket.on('data', (chunk) => {
+        received += chunk;
+        if (received.includes('\n') || received.length >= expected.length) {
+          settle(received === expected);
+        }
+      });
+      socket.once('end', () => settle(received === expected));
+      socket.once('error', () => settle(false));
+    } catch {
+      settle(false);
+    }
+  }
+
+  function bindCandidate(targetIndex, candidateIndex, boundForTarget, attemptGeneration) {
+    if (finished || attemptGeneration !== generation) return;
+    const target = targets[targetIndex];
+    if (candidateIndex === target.ports.length) {
+      if (boundForTarget === 0) {
+        retryCleanly(attemptGeneration);
+      } else {
+        bindTarget(targetIndex + 1, attemptGeneration);
+      }
+      return;
+    }
+    const port = target.ports[candidateIndex];
+    let candidate;
+    try {
+      candidate = net.createServer((socket) => serveLock(socket, target.identity));
+      const bindError = (error) => {
+        if (finished || attemptGeneration !== generation) return;
+        if (error?.code !== 'EADDRINUSE') {
+          requestTerminalFailure();
+          return;
+        }
+        probeOccupant(port, target.identity, (matching) => {
+          if (finished || attemptGeneration !== generation) return;
+          if (matching) retryCleanly(attemptGeneration);
+          else bindCandidate(targetIndex, candidateIndex + 1, boundForTarget, attemptGeneration);
+        });
+      };
+      candidate.once('error', bindError);
+      candidate.listen({ host: '127.0.0.1', port, exclusive: true }, () => {
+        if (finished || attemptGeneration !== generation) {
+          try { candidate.close(); } catch {}
+          return;
+        }
+        candidate.off('error', bindError);
+        candidate.on('error', requestTerminalFailure);
+        servers.push(candidate);
+        bindCandidate(targetIndex, candidateIndex + 1, boundForTarget + 1, attemptGeneration);
+      });
+    } catch {
+      requestTerminalFailure();
+    }
+  }
+
+  function bindTarget(index, attemptGeneration) {
+    if (finished || attemptGeneration !== generation) return;
+    if (index === targets.length) {
+      publish(states.ACQUIRED);
+      return;
+    }
+    bindCandidate(index, 0, 0, attemptGeneration);
+  }
+
+  function attemptAll() {
+    if (finished) return;
+    if (contentionDeadline !== null && performance.now() >= contentionDeadline) {
+      finish(states.TIMEOUT);
+      return;
+    }
+    const attemptGeneration = generation;
+    bindTarget(0, attemptGeneration);
+  }
+
+  parentPort.on('message', (message) => {
+    if (message?.type !== 'release' || releasing ||
+        Atomics.load(state, STATE_INDEX) !== states.ACQUIRED) return;
+    releasing = true;
+    generation += 1;
+    closeServers((error) => {
+      if (terminalFailureRequested) finish(states.FAILED, 1);
+      else finish(error ? states.RELEASE_FAILED : states.RELEASED, error ? 1 : 0);
+    });
+  });
+
+  try {
+    if (!Array.isArray(targets) || targets.length === 0 || targets.some((target) =>
+      !/^[a-f0-9]{64}$/.test(target?.identity) ||
+      !Array.isArray(target?.ports) || target.ports.length === 0 ||
+      target.ports.some((port) => !Number.isInteger(port) || port < 1 || port > 65535))) {
+      throw new TypeError('file lock worker requires valid targets');
+    }
+    attemptAll();
+  } catch {
+    requestTerminalFailure();
+  }
+}