velocious 1.0.630 → 1.0.631

package/README.md

@@ -34,7 +34,7 @@
 * Cross-process broadcast bus for `broadcastToChannel` via `velocious beacon`, including background job runner processes (see [docs/beacon.md](docs/beacon.md))
 * Configurable HTTP server worker handlers plus backpressured, descriptor-only file responses with completion callbacks (see [docs/http-server.md](docs/http-server.md))
 * Default-on buffered HTTP response compression with Brotli/gzip content negotiation, global and per-response opt-outs, and HEAD-correct representation headers (see [docs/http-server.md](docs/http-server.md#response-compression))
-* Background jobs with Node SQL/TCP workers plus a Browser/Expo local SQLite store and in-process dispatcher, including failure events and authorized database-scoped dashboard count snapshots/deltas. Release-directory integrations have a required release-scoped jobs-main/worker generation and asynchronous retirement compliance target that current startup adoption does not implement end to end (see [docs/background-jobs.md](docs/background-jobs.md), [docs/local-background-jobs.md](docs/local-background-jobs.md), and [docs/background-jobs-dashboard.md](docs/background-jobs-dashboard.md))
+* Background jobs with Node SQL/TCP workers plus a Browser/Expo local SQLite store and in-process dispatcher, including failure events, authorized database-scoped dashboard counts, and an opt-in release-scoped main/worker generation protocol with acknowledged activation, asynchronous retirement, and retired-main recovery. Production compliance additionally requires downstream supervisor retention/activation ordering and release pins (see [docs/background-jobs.md](docs/background-jobs.md), [docs/local-background-jobs.md](docs/local-background-jobs.md), and [docs/background-jobs-dashboard.md](docs/background-jobs-dashboard.md))
 * Durable one-off background-job scheduling with exact epoch timestamps (see [docs/scheduled-background-job-enqueue.md](docs/scheduled-background-job-enqueue.md))
 * Rails-style request and database query logging (see [docs/logging.md](docs/logging.md))
 * EJS-backed mailers with delivery, queueing, and payload rendering support (see [docs/mailers.md](docs/mailers.md))
@@ -2321,6 +2321,11 @@ the new main. Deploy and HTTP/WebSocket drain completion are independent of this
 potentially hours-long lifecycle. See [release-generation
 draining](docs/background-jobs.md#release-generation-draining).
 
+Velocious provides the opt-in generation protocol; production still requires a
+supervisor that preserves old generation units and release pins, and a deploy
+coordinator that retires the old generation before activating the healthy
+candidate without waiting for retired work to finish.
+
 Jobs can opt into cross-worker durable concurrency limits by pairing a non-empty `concurrencyKey` with a positive-integer `maxConcurrency` in their background-job options, or by deriving the key in a hydrated job instance's non-static `concurrencyKey()` method. Explicit enqueue options win. The first cap registered for a key is stable; conflicting caps are rejected. See [durable concurrency limits](docs/background-jobs.md#durable-concurrency-limits).
 
 Production apps can listen for `background-job-failed` (or its `all-error` mirror) to report accepted failed attempts, including retry and terminal-state metadata, and for `background-job-orphaned` to react to a specific job the main process reclaimed after its worker died mid-run — e.g. enqueue a targeted recovery for the work it left behind, instead of only polling for the aftermath. Orphan handlers run before the sweep waits for reclaimed jobs to be dispatched, so a stalled dispatcher does not delay application recovery. See [docs/background-jobs.md](docs/background-jobs.md#failure-events).
@@ -2365,7 +2370,11 @@ export default new Configuration({
     pooledRunnerMaxRssBytes: 536870912,
     pooledRunnerMaxLifetimeMs: 3600000,
     dispatchStrategy: "beacon",
-    jobTimeoutMs: null
+    jobTimeoutMs: null,
+    // Release-directory deployments opt in with one exact id and local socket:
+    generationId: "release-20260828.1",
+    initialGenerationState: "candidate",
+    lifecycleSocketPath: "/srv/app/releases/20260828.1/run/background-jobs.sock"
   }
 })
 ```
@@ -2428,8 +2437,32 @@ VELOCIOUS_BACKGROUND_JOBS_DISPATCH_STRATEGY=beacon
 VELOCIOUS_BACKGROUND_JOBS_POLL_INTERVAL_MS=1000
 VELOCIOUS_BACKGROUND_JOBS_WORKER_SHUTDOWN_TIMEOUT_MS=indefinite
 VELOCIOUS_BACKGROUND_JOBS_JOB_TIMEOUT_MS=5400000
+# Opt-in release generation values (omit all three for exact legacy behavior):
+VELOCIOUS_BACKGROUND_JOBS_GENERATION_ID=release-20260828.1
+VELOCIOUS_BACKGROUND_JOBS_INITIAL_GENERATION_STATE=candidate
+VELOCIOUS_BACKGROUND_JOBS_LIFECYCLE_SOCKET_PATH=/srv/app/releases/20260828.1/run/background-jobs.sock
 ```
 
+Activate or retire that exact generation with one acknowledged local request:
+
+```sh
+npx velocious background-jobs:activate --generation release-20260828.1 --socket /srv/app/releases/20260828.1/run/background-jobs.sock
+npx velocious background-jobs:retire --generation release-20260828.1 --socket /srv/app/releases/20260828.1/run/background-jobs.sock
+```
+
+Each lifecycle command sends one request with no retry and has a hard 10000ms
+deadline; `--timeout-ms` accepts 1 through 25000ms. Generation-aware workers,
+clients, and reporters require their hello acknowledgement before readiness or
+mutation and bound it to 4000ms by default.
+
+Generation ids supplied through config, environment, API, or CLI must be
+identical and match `^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$`; invalid or conflicting
+identity fails before listening. Omit generation settings to preserve legacy
+worker ids, protocol, disconnect recovery, and custom-adapter compatibility.
+An ID-only configuration derives `candidate`; that default does not conflict
+with an explicit API/CLI `active` or `retired` recovery state, while multiple
+actual state sources must still agree.
+
 `VELOCIOUS_BACKGROUND_JOBS_WORKER_SHUTDOWN_TIMEOUT_MS` (default: `indefinite`) bounds how long a `background-jobs-worker` waits for in-flight jobs on `SIGTERM`/`SIGINT` before terminating any forked or spawned child runners still running. The default waits for jobs to finish and never interrupts a running job; a positive finite cap is a per-worker shutdown control for an explicitly requested process stop, not the normal deploy-completion mechanism. During release retirement, the old jobs-main and workers may drain for hours after deploy returns. See [docs/background-jobs.md](docs/background-jobs.md#worker-shutdown-and-process-job-draining).
 
 `maxConcurrentInlineJobs` (default: `4`) caps how many `executionMode: "inline"` jobs a single `background-jobs-worker` process runs in parallel. Concurrency is at the JS event-loop level: every job in flight shares the worker's process and DB connection pool, so the cap should fit the pool, not the CPU count. Forking remains the right tool when you need memory isolation across long-running jobs or want to use more cores; select it with `executionMode: "forked"`.
@@ -2637,7 +2670,7 @@ Each job must define exactly one of `every` or `cron`. Cron times are evaluated
 
 ## Persistence and retries
 
-Jobs are persisted in the configured database (`backgroundJobs.databaseIdentifier`) in an internal `background_jobs` table. When a worker picks a job, the main generates a unique lease id before asking the adapter to mark the job handed off, and the worker reports completion or failure back to the main process. If that persistence call has an ambiguous result, only the exact caller-generated lease is conditionally returned; failed recovery is retained for the dispatch error-retry path, so worker admission and concurrency do not remain stranded and a newer lease is never reclaimed. Custom adapters must persist a supplied `markHandedOff({handoffId})` exactly; built-in adapters continue generating one for legacy direct callers that omit it. If a worker socket disconnects unexpectedly, only the leases handed to that exact socket are immediately returned to the queue; late reports are fenced by lease id so they cannot mutate a newer attempt. This recovery is at-least-once and may repeat application side effects if the disconnected attempt had already started them. Gracefully draining workers keep their leases while they finish. Startup reconnection/adoption is an abnormal crash/legacy-recovery facility, not the normal deploy topology: during ordinary release retirement the old main remains alive and owns its old workers, and they must not reconnect to the new main. A production integration that restarts jobs-main every deploy and depends on worker adoption is not compliant with the release-generation contract. See [release-generation draining](docs/background-jobs.md#release-generation-draining) and [worker disconnect recovery](docs/background-jobs.md#worker-disconnect-recovery).
+Jobs are persisted in the configured database (`backgroundJobs.databaseIdentifier`) in an internal `background_jobs` table. When a worker picks a job, the main generates a unique lease id before asking the adapter to mark the job handed off, and the worker reports completion or failure back to the main process. If that persistence call has an ambiguous result, only the exact caller-generated lease is conditionally returned; failed recovery is retained for the dispatch error-retry path, so worker admission and concurrency do not remain stranded and a newer lease is never reclaimed. Custom adapters must persist a supplied `markHandedOff({handoffId})` exactly; built-in adapters continue generating one for legacy direct callers that omit it. A legacy worker disconnect returns only that socket's leases immediately. Generation mode instead preserves the exact leases through reconnect grace for the same qualified worker, then returns them to the global queue on expiry. Late reports are fenced by generation-qualified worker id, lease id, and handoff time so they cannot mutate a newer attempt. This recovery is at-least-once and may repeat application side effects if the disconnected attempt had already started them. A release-retiring worker revokes readiness but retains heartbeat, its unchanged old endpoint, exact-generation reconnect, accepted work, child execution, durable reports, and acknowledgements until its drain settles; retiring/retired mains reject new identities and never grant reconnecting workers readiness. Startup reconnection/adoption is an abnormal crash/legacy-recovery facility, not the normal deploy topology: during ordinary release retirement the old main remains alive and owns its old workers, and they must not reconnect to the new main. A production integration that restarts jobs-main on every deploy and depends on worker adoption is not compliant with the release-generation contract. See [release-generation draining](docs/background-jobs.md#release-generation-draining) and [worker disconnect recovery](docs/background-jobs.md#worker-disconnect-recovery).
 
 Failed jobs are re-queued with backoff and retried up to 10 times by default (10s, 1m, 10m, 1h, then +1h per retry). You can override the retry limit per job:
 

package/build/background-jobs/adapter.js

@@ -6,6 +6,14 @@
  * separate concerns.
  */
 export default class BackgroundJobsAdapter {
+  /**
+   * Declares exact durable fencing support for release-scoped generations.
+   * Third-party adapters must override this only after implementing the full
+   * snapshot, owner, report, and recovery contract.
+   * @returns {boolean} - Whether generation mode is supported.
+   */
+  supportsReleaseScopedGenerations() { return false }
+
   /**
    * Ensures the adapter can accept work.
    * @returns {Promise<void>} - Resolves when ready.

package/build/background-jobs/client.js

@@ -3,6 +3,7 @@
 import timeout from "awaitery/build/timeout.js"
 import configurationResolver from "../configuration-resolver.js"
 import BackgroundJobsSocketRequest from "./socket-request.js"
+import { DEFAULT_GENERATION_HANDSHAKE_TIMEOUT_MS, validateGenerationHandshakeTimeoutMs } from "./generation-handshake-timeout-error.js"
 
 const DEFAULT_ENQUEUE_TIMEOUT_MS = 5000
 
@@ -12,10 +13,14 @@ export default class BackgroundJobsClient {
    * @param {object} [args] - Options.
    * @param {import("../configuration.js").default} [args.configuration] - Configuration.
    * @param {number} [args.enqueueTimeoutMs] - Maximum time to wait for an enqueue acknowledgement in milliseconds (default: 5000).
+   * @param {number} [args.generationHandshakeTimeoutMs] - Maximum time to wait for generation acknowledgement (default: 4000).
+   * @param {string} [args.generationId] - Explicit release generation identity.
    */
-  constructor({configuration, enqueueTimeoutMs = DEFAULT_ENQUEUE_TIMEOUT_MS} = {}) {
+  constructor({configuration, enqueueTimeoutMs = DEFAULT_ENQUEUE_TIMEOUT_MS, generationHandshakeTimeoutMs = DEFAULT_GENERATION_HANDSHAKE_TIMEOUT_MS, generationId} = {}) {
     this.configurationPromise = configuration ? Promise.resolve(configuration) : configurationResolver()
     this.enqueueTimeoutMs = enqueueTimeoutMs
+    this.generationHandshakeTimeoutMs = validateGenerationHandshakeTimeoutMs(generationHandshakeTimeoutMs)
+    this.explicitGenerationId = generationId
   }
 
   /**
@@ -25,8 +30,12 @@ export default class BackgroundJobsClient {
   async _request() {
     const configuration = await this.configurationPromise
     const {host, port} = configuration.getBackgroundJobsConfig()
+    const {generationId} = configuration.resolveBackgroundJobsGenerationConfig({
+      generationId: this.explicitGenerationId,
+      sourceName: "BackgroundJobsClient"
+    })
 
-    return new BackgroundJobsSocketRequest({host, port, role: "client"})
+    return new BackgroundJobsSocketRequest({host, port, role: "client", generationHandshakeTimeoutMs: this.generationHandshakeTimeoutMs, generationId})
   }
 
   /**

package/build/background-jobs/generation-handshake-timeout-error.js

@@ -0,0 +1,32 @@
+// @ts-check
+
+export const DEFAULT_GENERATION_HANDSHAKE_TIMEOUT_MS = 4000
+
+/** Actionable failure for an unacknowledged generation hello. */
+export default class BackgroundJobsGenerationHandshakeTimeoutError extends Error {
+  /**
+   * Creates an actionable generation-handshake deadline failure.
+   * @param {object} args - Timeout context.
+   * @param {string} args.endpoint - Main endpoint.
+   * @param {string} args.generationId - Expected generation.
+   * @param {"worker" | "client" | "reporter"} args.role - Initiating peer role.
+   * @param {number} args.timeoutMs - Handshake deadline.
+   */
+  constructor({endpoint, generationId, role, timeoutMs}) {
+    super(`Background jobs ${role} generation handshake for ${generationId} timed out after ${timeoutMs}ms at ${endpoint}`)
+    this.name = "BackgroundJobsGenerationHandshakeTimeoutError"
+  }
+}
+
+/**
+ * Validates a generation handshake deadline.
+ * @param {number} timeoutMs - Candidate deadline.
+ * @returns {number} - Valid deadline.
+ */
+export function validateGenerationHandshakeTimeoutMs(timeoutMs) {
+  if (!Number.isInteger(timeoutMs) || timeoutMs < 1 || timeoutMs > 2_147_483_647) {
+    throw new TypeError("generationHandshakeTimeoutMs must be an integer between 1 and 2147483647")
+  }
+
+  return timeoutMs
+}

package/build/background-jobs/generation-identity.js

@@ -0,0 +1,160 @@
+// @ts-check
+
+import { utf8ByteLength } from "../utils/utf8-byte-length.js"
+
+/**
+ * @typedef {object} GenerationValueSource
+ * @property {string} name - Human-readable source name.
+ * @property {boolean} present - Whether the source was explicitly supplied.
+ * @property {ReturnType<typeof JSON.parse> | undefined} value - Supplied value.
+ */
+
+const GENERATION_ID_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/
+const WORKER_INSTANCE_ID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i
+const INITIAL_GENERATION_STATES = new Set(["candidate", "active", "retired"])
+
+/**
+ * Validates one release generation identifier.
+ * @param {ReturnType<typeof JSON.parse> | undefined} value - Candidate value.
+ * @param {string} [sourceName] - Source label for failures.
+ * @returns {string} - Valid generation id.
+ */
+export function validateGenerationId(value, sourceName = "background jobs generationId") {
+  if (typeof value !== "string" || !GENERATION_ID_PATTERN.test(value)) {
+    throw new TypeError(`${sourceName} must match ${GENERATION_ID_PATTERN}`)
+  }
+
+  return value
+}
+
+/**
+ * Resolves explicitly present generation identity sources without precedence.
+ * @param {GenerationValueSource[]} sources - Identity sources.
+ * @returns {string | undefined} - Identical resolved identity or legacy unset.
+ */
+export function resolveGenerationId(sources) {
+  const presentSources = sources.filter((source) => source.present)
+
+  if (presentSources.length === 0) return undefined
+
+  const values = presentSources.map((source) => validateGenerationId(source.value, source.name))
+  const generationId = values[0]
+
+  if (values.some((value) => value !== generationId)) {
+    const names = presentSources.map((source) => source.name).join(", ")
+
+    throw new Error(`Conflicting background jobs generation identities from: ${names}`)
+  }
+
+  return generationId
+}
+
+/**
+ * Resolves the boot lifecycle state.
+ * @param {GenerationValueSource[]} sources - State sources.
+ * @param {string | undefined} generationId - Resolved generation identity.
+ * @returns {import("./types.js").BackgroundJobsGenerationInitialState | "active"} - Boot state.
+ */
+export function resolveInitialGenerationState(sources, generationId) {
+  const presentSources = sources.filter((source) => source.present)
+
+  if (presentSources.length === 0) return generationId ? "candidate" : "active"
+  if (!generationId) throw new Error("backgroundJobs.initialGenerationState requires backgroundJobs.generationId")
+
+  const values = presentSources.map((source) => {
+    if (typeof source.value !== "string" || !INITIAL_GENERATION_STATES.has(source.value)) {
+      throw new TypeError(`${source.name} must be "candidate", "active", or "retired"`)
+    }
+
+    return /** @type {import("./types.js").BackgroundJobsGenerationInitialState} */ (source.value)
+  })
+  const state = values[0]
+
+  if (values.some((value) => value !== state)) {
+    const names = presentSources.map((source) => source.name).join(", ")
+
+    throw new Error(`Conflicting background jobs initialGenerationState values from: ${names}`)
+  }
+
+  return state
+}
+
+/**
+ * Resolves the optional release-local lifecycle socket path.
+ * @param {GenerationValueSource[]} sources - Path sources.
+ * @param {string | undefined} generationId - Resolved generation identity.
+ * @returns {string | undefined} - Absolute Unix socket path.
+ */
+export function resolveLifecycleSocketPath(sources, generationId) {
+  const presentSources = sources.filter((source) => source.present)
+
+  if (presentSources.length === 0) return undefined
+  if (!generationId) throw new Error("backgroundJobs.lifecycleSocketPath requires backgroundJobs.generationId")
+
+  const values = presentSources.map((source) => {
+    if (typeof source.value !== "string" || !source.value.startsWith("/") || source.value.includes("\0")) {
+      throw new TypeError(`${source.name} must be an absolute Unix socket path`)
+    }
+
+    if (utf8ByteLength(source.value) > 103) {
+      throw new TypeError(`${source.name} must be at most 103 UTF-8 bytes for portable Unix socket support`)
+    }
+
+    return source.value
+  })
+  const socketPath = values[0]
+
+  if (values.some((value) => value !== socketPath)) {
+    const names = presentSources.map((source) => source.name).join(", ")
+
+    throw new Error(`Conflicting background jobs lifecycle socket paths from: ${names}`)
+  }
+
+  return socketPath
+}
+
+/**
+ * Creates the exact durable worker owner token.
+ * @param {object} args - Owner parts.
+ * @param {string} args.generationId - Release generation.
+ * @param {string} args.workerInstanceId - Worker process UUID.
+ * @returns {string} - Generation-qualified durable worker id.
+ */
+export function createGenerationWorkerId({generationId, workerInstanceId}) {
+  validateGenerationId(generationId)
+  if (!WORKER_INSTANCE_ID_PATTERN.test(workerInstanceId)) throw new TypeError("workerInstanceId must be a UUID")
+
+  return `${generationId}:${workerInstanceId}`
+}
+
+/**
+ * Parses a generation-qualified durable worker id.
+ * @param {ReturnType<typeof JSON.parse>} workerId - Durable worker id.
+ * @returns {{generationId: string, workerInstanceId: string} | null} - Parsed owner or null.
+ */
+export function parseGenerationWorkerId(workerId) {
+  if (typeof workerId !== "string") return null
+
+  const separatorIndex = workerId.indexOf(":")
+  if (separatorIndex < 1 || separatorIndex !== workerId.lastIndexOf(":")) return null
+
+  const generationId = workerId.slice(0, separatorIndex)
+  const workerInstanceId = workerId.slice(separatorIndex + 1)
+
+  if (!GENERATION_ID_PATTERN.test(generationId) || !WORKER_INSTANCE_ID_PATTERN.test(workerInstanceId)) return null
+
+  return {generationId, workerInstanceId}
+}
+
+/**
+ * Checks exact parsed generation ownership.
+ * @param {object} args - Ownership query.
+ * @param {string} args.generationId - Expected generation.
+ * @param {ReturnType<typeof JSON.parse>} args.workerId - Durable worker id.
+ * @returns {boolean} - Whether the parsed owner belongs to the generation.
+ */
+export function workerIdBelongsToGeneration({generationId, workerId}) {
+  const parsed = parseGenerationWorkerId(workerId)
+
+  return parsed?.generationId === generationId
+}

package/build/background-jobs/lifecycle-client.js

@@ -0,0 +1,127 @@
+// @ts-check
+
+import { randomUUID } from "node:crypto"
+import net from "node:net"
+import timeout from "awaitery/build/timeout.js"
+import JsonSocket from "./json-socket.js"
+
+const DEFAULT_REQUEST_TIMEOUT_MS = 10000
+const MAX_REQUEST_TIMEOUT_MS = 25000
+
+/** One-request acknowledged lifecycle client. */
+export default class BackgroundJobsLifecycleClient {
+  /**
+   * Creates a lifecycle client.
+   * @param {object} args - Client options.
+   * @param {import("../configuration.js").default} args.configuration - Configuration.
+   * @param {string} [args.generationId] - Explicit generation identity.
+   * @param {string} [args.socketPath] - Explicit control socket path.
+   * @param {number} [args.requestTimeoutMs] - Request deadline below the supervisor hook timeout (default: 10000).
+   */
+  constructor({configuration, generationId, socketPath, requestTimeoutMs = DEFAULT_REQUEST_TIMEOUT_MS}) {
+    const generationConfig = configuration.resolveBackgroundJobsGenerationConfig({
+      generationId,
+      lifecycleSocketPath: socketPath,
+      sourceName: "BackgroundJobsLifecycleClient"
+    })
+    this.generationId = generationConfig.generationId
+    this.socketPath = generationConfig.lifecycleSocketPath
+    if (!Number.isInteger(requestTimeoutMs) || requestTimeoutMs < 1 || requestTimeoutMs > MAX_REQUEST_TIMEOUT_MS) {
+      throw new TypeError(`requestTimeoutMs must be an integer between 1 and ${MAX_REQUEST_TIMEOUT_MS}`)
+    }
+    this.requestTimeoutMs = requestTimeoutMs
+    if (!this.generationId) throw new Error("Background jobs lifecycle client requires generationId")
+    if (!this.socketPath) throw new Error("Background jobs lifecycle client requires lifecycleSocketPath")
+  }
+
+  /**
+   * Activates the generation.
+   * @returns {Promise<import("./types.js").BackgroundJobsGenerationLifecycleState>} - Resulting state.
+   */
+  async activate() { return await this._request("activate") }
+
+  /**
+   * Retires the generation.
+   * @returns {Promise<import("./types.js").BackgroundJobsGenerationLifecycleState>} - Resulting state.
+   */
+  async retire() { return await this._request("retire") }
+
+  /**
+   * Sends exactly one lifecycle request.
+   * @param {"activate" | "retire"} action - Lifecycle action.
+   * @returns {Promise<import("./types.js").BackgroundJobsGenerationLifecycleState>} - Resulting state.
+   */
+  async _request(action) {
+    return await timeout({
+      errorMessage: `Background jobs ${action} request for ${this.generationId} timed out after ${this.requestTimeoutMs}ms at ${this.socketPath}`,
+      timeout: this.requestTimeoutMs
+    }, async ({control}) => await this._runRequest({action, signal: control.signal}))
+  }
+
+  /**
+   * Sends the lifecycle request under its caller-owned deadline.
+   * @param {object} args - Request details.
+   * @param {"activate" | "retire"} args.action - Lifecycle action.
+   * @param {AbortSignal} args.signal - Request deadline signal.
+   * @returns {Promise<import("./types.js").BackgroundJobsGenerationLifecycleState>} - Resulting state.
+   */
+  async _runRequest({action, signal}) {
+    const requestId = randomUUID()
+    const socket = net.createConnection(this.socketPath)
+    const jsonSocket = new JsonSocket(socket)
+
+    return await new Promise((resolve, reject) => {
+      let finished = false
+      /**
+       * Settles the request once.
+       * @param {object} options - Teardown options.
+       * @param {boolean} [options.destroy] - Destroy instead of closing.
+       * @param {() => void} callback - Settlement callback.
+       */
+      const finish = ({destroy = false}, callback) => {
+        if (finished) return
+        finished = true
+        signal.removeEventListener("abort", onAbort)
+        socket.removeListener("connect", onConnect)
+        jsonSocket.removeAllListeners()
+        if (destroy) jsonSocket.destroy()
+        else jsonSocket.close()
+        callback()
+      }
+
+      const onAbort = () => finish({destroy: true}, () => reject(signal.reason instanceof Error ? signal.reason : new Error("Background jobs lifecycle request aborted")))
+      const onConnect = () => {
+        jsonSocket.send({
+          type: "background-jobs-lifecycle",
+          action,
+          generationId: this.generationId,
+          requestId
+        })
+      }
+
+      signal.addEventListener("abort", onAbort)
+      jsonSocket.on("error", (error) => finish({}, () => reject(error)))
+      jsonSocket.on("close", () => finish({destroy: true}, () => reject(new Error("Background jobs lifecycle socket closed before acknowledgement"))))
+      jsonSocket.on("message", (message) => {
+        if (message?.requestId !== requestId || message.action !== action) {
+          finish({}, () => reject(new Error("Background jobs lifecycle response did not match its request")))
+          return
+        }
+        if (message.type === "background-jobs-lifecycle-error") {
+          const error = new Error(message.error?.message || "Background jobs lifecycle request failed")
+          if (typeof message.error?.name === "string") error.name = message.error.name
+          if (typeof message.error?.stack === "string") error.stack = message.error.stack
+          finish({}, () => reject(error))
+          return
+        }
+        if (message.type !== "background-jobs-lifecycle-ack" || message.generationId !== this.generationId) {
+          finish({}, () => reject(new Error("Invalid background jobs lifecycle acknowledgement")))
+          return
+        }
+        finish({}, () => resolve(message.lifecycleState))
+      })
+      socket.once("connect", onConnect)
+      if (signal.aborted) onAbort()
+    })
+  }
+}