velocious 1.0.528 → 1.0.529

package/src/background-jobs/store.js

@@ -18,8 +18,25 @@ const ORPHANED_AFTER_MS = 2 * 60 * 60 * 1000
 /**
  * Execution modes.
  * @type {import("./types.js").BackgroundJobExecutionMode[]} */
-const EXECUTION_MODES = ["inline", "forked", "spawned"]
-const DEFAULT_EXECUTION_MODE = "forked"
+const EXECUTION_MODES = ["inline", "forked", "pooled", "spawned"]
+/**
+ * Execution mode for a new enqueue that names neither `executionMode` nor the
+ * legacy `forked` flag. Pooled routes the job to a warm, reused local runner
+ * process — the same isolation as forked without paying a fresh process per job.
+ * @type {import("./types.js").BackgroundJobExecutionMode} */
+const DEFAULT_EXECUTION_MODE = "pooled"
+/**
+ * Execution mode a legacy `forked = true` row (persisted before the
+ * `execution_mode` column existed) backfills to. It must stay `"forked"` so an
+ * upgrade never silently reinterprets already-persisted forked jobs as pooled —
+ * distinct from {@link DEFAULT_EXECUTION_MODE}, which only governs new enqueues.
+ * @type {import("./types.js").BackgroundJobExecutionMode} */
+const LEGACY_FORKED_EXECUTION_MODE = "forked"
+// Pooled jobs persist with the legacy-safe `forked` mode so a pre-pool main can
+// deserialize and run them during a rolling upgrade. Old versions ignore the
+// nullable handoff id on queued rows, making it a backward-compatible marker.
+const POOLED_HANDOFF_ID_PREFIX = "velocious-pooled:"
+const POOLED_QUEUED_HANDOFF_ID = `${POOLED_HANDOFF_ID_PREFIX}queued`
 const DEFAULT_QUEUE = "default"
 // Queue-derived durable concurrency keys are namespaced so they can't collide
 // with explicit caller-supplied concurrencyKeys.
@@ -138,7 +155,7 @@ export default class BackgroundJobsStore {
           job_name: jobName,
           args_json: argsJson,
           forked: executionMode !== "inline",
-          execution_mode: executionMode,
+          execution_mode: executionMode === "pooled" ? LEGACY_FORKED_EXECUTION_MODE : executionMode,
           queue,
           max_retries: maxRetries,
           attempts: 0,
@@ -146,7 +163,8 @@ export default class BackgroundJobsStore {
           scheduled_at_ms: scheduledAtMs,
           created_at_ms: now,
           concurrency_key: concurrency?.concurrencyKey || null,
-          max_concurrency: concurrency?.maxConcurrency || null
+          max_concurrency: concurrency?.maxConcurrency || null,
+          handoff_id: executionMode === "pooled" ? POOLED_QUEUED_HANDOFF_ID : null
         }
       })
     })
@@ -221,11 +239,7 @@ export default class BackgroundJobsStore {
     if (typeof forked === "boolean") {
       query = query.where({forked})
     }
-    if (executionMode) {
-      const executionModes = Array.isArray(executionMode) ? executionMode : [executionMode]
-
-      query = query.where({execution_mode: executionModes})
-    }
+    if (executionMode) query = this._whereExecutionMode({db, executionMode, query})
 
     if (scheduledAtOperator === "<=") {
       const priorityOrder = this._queuePriorityOrderSql(db)
@@ -401,12 +415,14 @@ export default class BackgroundJobsStore {
     await this.ensureReady()
 
     const handedOffAtMs = Date.now()
-    const handoffId = randomUUID()
 
     return await this._withDb(async (db) => await this._transactionResult(db, async () => {
       const queuedJob = await this._getJobRowById(db, jobId)
       if (!queuedJob || queuedJob.status !== "queued") return null
       if (queuedJob.concurrencyKey && !(await this._reserveConcurrency(db, queuedJob.concurrencyKey))) return null
+      const handoffId = queuedJob.executionMode === "pooled"
+        ? `${POOLED_HANDOFF_ID_PREFIX}${randomUUID()}`
+        : randomUUID()
 
       const affectedRows = await this._updateAffectedRows(db, {
         tableName: JOBS_TABLE,
@@ -480,7 +496,7 @@ export default class BackgroundJobsStore {
           status: "queued",
           scheduled_at_ms: Date.now(),
           handed_off_at_ms: null,
-          handoff_id: null,
+          handoff_id: job.executionMode === "pooled" ? POOLED_QUEUED_HANDOFF_ID : null,
           worker_id: null
         },
         conditions: {handoff_id: handoffId, id: jobId, status: "handed_off"}
@@ -990,7 +1006,7 @@ export default class BackgroundJobsStore {
       const executionModeColumnSql = db.quoteColumn("execution_mode")
 
       await db.query(
-        `UPDATE ${tableNameSql} SET ${executionModeColumnSql} = ${db.quote(DEFAULT_EXECUTION_MODE)} ` +
+        `UPDATE ${tableNameSql} SET ${executionModeColumnSql} = ${db.quote(LEGACY_FORKED_EXECUTION_MODE)} ` +
         `WHERE ${forkedColumnSql} = ${db.quote(true)} AND ${executionModeColumnSql} IS NULL`
       )
       await db.query(
@@ -1081,6 +1097,7 @@ export default class BackgroundJobsStore {
       scheduledAt,
       shouldRetry
     })
+    if (shouldRetry && job.executionMode === "pooled") update.handoff_id = POOLED_QUEUED_HANDOFF_ID
 
     const affectedRows = await this._updateAffectedRows(db, {
       tableName: JOBS_TABLE,
@@ -1189,8 +1206,10 @@ export default class BackgroundJobsStore {
    * @returns {import("./types.js").BackgroundJobRow} - Normalized job row.
    */
   _normalizeJobRow(row) {
-    const executionMode = row.execution_mode
-      ? this._normalizeExecutionModeName(String(row.execution_mode))
+    const persistedExecutionMode = row.execution_mode ? String(row.execution_mode) : null
+    const handoffId = row.handoff_id ? String(row.handoff_id) : null
+    const executionMode = persistedExecutionMode
+      ? this._normalizePersistedExecutionMode({executionMode: persistedExecutionMode, handoffId})
       : this._normalizeExecutionMode({forked: this._normalizeBoolean(row.forked)})
 
     return {
@@ -1206,7 +1225,7 @@ export default class BackgroundJobsStore {
       scheduledAtMs: this._normalizeNumber(row.scheduled_at_ms),
       createdAtMs: this._normalizeNumber(row.created_at_ms),
       handedOffAtMs: this._normalizeNumber(row.handed_off_at_ms),
-      handoffId: row.handoff_id ? String(row.handoff_id) : null,
+      handoffId,
       completedAtMs: this._normalizeNumber(row.completed_at_ms),
       failedAtMs: this._normalizeNumber(row.failed_at_ms),
       orphanedAtMs: this._normalizeNumber(row.orphaned_at_ms),
@@ -1506,7 +1525,11 @@ export default class BackgroundJobsStore {
     if (executionMode) {
       return this._normalizeExecutionModeName(executionMode)
     }
+    // The legacy `forked` flag stays authoritative when supplied: `false` is
+    // inline and `true` is forked (never the pooled default). Only an enqueue
+    // that names neither option falls through to the pooled default.
     if (options?.forked === false) return "inline"
+    if (options?.forked === true) return LEGACY_FORKED_EXECUTION_MODE
 
     return DEFAULT_EXECUTION_MODE
   }
@@ -1524,6 +1547,47 @@ export default class BackgroundJobsStore {
     throw new Error(`Invalid background job executionMode: ${executionMode}`)
   }
 
+  /**
+   * Normalizes a legacy-safe persisted execution mode.
+   * @param {object} args - Options.
+   * @param {string} args.executionMode - Persisted legacy execution mode.
+   * @param {string | null} args.handoffId - Persisted handoff id or pooled marker.
+   * @returns {import("./types.js").BackgroundJobExecutionMode} - Runtime execution mode.
+   */
+  _normalizePersistedExecutionMode({executionMode, handoffId}) {
+    if (executionMode === LEGACY_FORKED_EXECUTION_MODE && handoffId?.startsWith(POOLED_HANDOFF_ID_PREFIX)) return "pooled"
+
+    return this._normalizeExecutionModeName(executionMode)
+  }
+
+  /**
+   * Filters persisted legacy-safe execution modes.
+   * @param {object} args - Options.
+   * @param {import("../database/drivers/base.js").default} args.db - Database connection.
+   * @param {import("./types.js").BackgroundJobExecutionMode | import("./types.js").BackgroundJobExecutionMode[]} args.executionMode - Runtime modes.
+   * @param {import("../database/query/index.js").default} args.query - Query to filter.
+   * @returns {import("../database/query/index.js").default} - Filtered query.
+   */
+  _whereExecutionMode({db, executionMode, query}) {
+    const executionModes = Array.isArray(executionMode) ? executionMode : [executionMode]
+    /** @type {string[]} */
+    const conditions = []
+    const executionModeColumn = db.quoteColumn("execution_mode")
+    const handoffIdColumn = db.quoteColumn("handoff_id")
+
+    for (const mode of executionModes) {
+      if (mode === "pooled") {
+        conditions.push(`(${executionModeColumn} = ${db.quote(LEGACY_FORKED_EXECUTION_MODE)} AND ${handoffIdColumn} = ${db.quote(POOLED_QUEUED_HANDOFF_ID)})`)
+      } else if (mode === LEGACY_FORKED_EXECUTION_MODE) {
+        conditions.push(`(${executionModeColumn} = ${db.quote(mode)} AND (${handoffIdColumn} IS NULL OR ${handoffIdColumn} <> ${db.quote(POOLED_QUEUED_HANDOFF_ID)}))`)
+      } else {
+        conditions.push(`${executionModeColumn} = ${db.quote(mode)}`)
+      }
+    }
+
+    return query.where(`(${conditions.join(" OR ")})`)
+  }
+
   /**
    * Runs parse args.
    * @param {?} value - Input value.

package/src/background-jobs/types.js

@@ -1,7 +1,7 @@
 // @ts-check
 
 /**
- * @typedef {"inline" | "forked" | "spawned"} BackgroundJobExecutionMode
+ * @typedef {"inline" | "forked" | "pooled" | "spawned"} BackgroundJobExecutionMode
  */
 /**
  * @typedef {object} BackgroundJobHandoff
@@ -10,8 +10,8 @@
  */
 /**
  * @typedef {object} BackgroundJobOptions
- * @property {BackgroundJobExecutionMode} [executionMode] - How the job should run. Defaults to `"forked"`.
- * @property {boolean} [forked] - Compatibility alias: `false` maps to `"inline"` and `true` maps to `"forked"`.
+ * @property {BackgroundJobExecutionMode} [executionMode] - How the job should run. Defaults to `"pooled"` (a warm, reused local runner process). `"forked"` runs the job in a fresh `child_process.fork()` child, `"spawned"` in a detached CLI runner, and `"inline"` inside the worker process.
+ * @property {boolean} [forked] - Compatibility alias: `false` maps to `"inline"` and `true` maps to `"forked"`. Omitting both `forked` and `executionMode` uses the default `"pooled"` mode.
  * @property {number} [maxRetries] - Max retries for a failed job before it is marked failed.
  * @property {string} [queue] - Queue name. Defaults to `"default"`. When the queue has a configured cap in `backgroundJobs.queues`, that cap is enforced cluster-wide.
  * @property {string} [concurrencyKey] - Opaque non-empty key used to share a concurrency cap. Overrides any queue-derived cap.
@@ -67,8 +67,8 @@
  * @typedef {"worker" | "client" | "reporter"} BackgroundJobSocketRole
  */
 /**
- * @typedef {{type: "hello", role: BackgroundJobSocketRole, supportsHandoffIdReporting?: boolean, supportsHeartbeat?: boolean, workerId?: string}} BackgroundJobHelloMessage
- * @typedef {{type: "ready", acceptsForked?: boolean, acceptsInline?: boolean, acceptsSpawned?: boolean}} BackgroundJobReadyMessage
+ * @typedef {{type: "hello", role: BackgroundJobSocketRole, supportsHandoffIdReporting?: boolean, supportsHeartbeat?: boolean, supportsPooled?: boolean, workerId?: string}} BackgroundJobHelloMessage
+ * @typedef {{type: "ready", acceptsForked?: boolean, acceptsInline?: boolean, acceptsPooled?: boolean, acceptsSpawned?: boolean}} BackgroundJobReadyMessage
  * @typedef {{type: "draining"}} BackgroundJobDrainingMessage
  * @typedef {{type: "heartbeat", workerId?: string}} BackgroundJobHeartbeatMessage
  * @typedef {{type: "enqueue", jobName: string, args?: Array<?>, options?: BackgroundJobOptions}} BackgroundJobEnqueueMessage

package/src/background-jobs/worker.js

@@ -19,6 +19,7 @@ const FORKED_CHILD_SIGKILL_GRACE_MS = 5000
  */
 const MAX_FORKED_JOB_TIMEOUT_MS = 2_147_483_647
 const FORKED_RUNNER_ENTRY_PATH = fileURLToPath(new URL("./forked-runner-child.js", import.meta.url))
+const POOLED_RUNNER_ENTRY_PATH = fileURLToPath(new URL("./pooled-runner-child.js", import.meta.url))
 /** How often the worker sends a liveness heartbeat to the main. */
 const HEARTBEAT_INTERVAL_MS = 15000
 /** TCP keepalive so a half-open connection to the main surfaces as a close. */
@@ -26,7 +27,25 @@ const SOCKET_KEEPALIVE_MS = 10000
 /**
  * Execution modes.
  * @type {import("./types.js").BackgroundJobExecutionMode[]} */
-const EXECUTION_MODES = ["inline", "forked", "spawned"]
+const EXECUTION_MODES = ["inline", "forked", "pooled", "spawned"]
+
+/**
+ * Normalizes a candidate pooled-runner count or job limit.
+ * @param {number | undefined} value - Candidate positive integer.
+ * @returns {number | undefined} - Normalized value.
+ */
+function positiveInteger(value) {
+  return typeof value === "number" && Number.isInteger(value) && value > 0 ? value : undefined
+}
+
+/**
+ * Normalizes a candidate pooled-runner resource limit.
+ * @param {number | undefined} value - Candidate positive number.
+ * @returns {number | undefined} - Normalized value.
+ */
+function positiveNumber(value) {
+  return typeof value === "number" && Number.isFinite(value) && value > 0 ? value : undefined
+}
 
 /**
  * Per-forked-child timeout bookkeeping.
@@ -46,11 +65,15 @@ export default class BackgroundJobsWorker {
    * @param {number} [args.port] - Port.
    * @param {number} [args.maxConcurrentForkedJobs] - Override the process runner concurrency cap from `configuration.getBackgroundJobsConfig()`.
    * @param {number} [args.maxConcurrentInlineJobs] - Override the inline-job concurrency cap from `configuration.getBackgroundJobsConfig()`.
+   * @param {number} [args.pooledRunnerCount] - Override the pooled runner count.
+   * @param {number} [args.pooledRunnerMaxJobs] - Override the per-runner recycle job count.
+   * @param {number} [args.pooledRunnerMaxRssBytes] - Override the per-runner recycle RSS limit.
+   * @param {number} [args.pooledRunnerMaxLifetimeMs] - Override the per-runner recycle lifetime.
    * @param {number} [args.forkedChildSigkillGraceMs] - Override the grace period between SIGTERM and SIGKILL when reaping lingering process runners on stop.
    * @param {number} [args.heartbeatIntervalMs] - Override the liveness heartbeat interval (default 15000ms).
    * @param {number} [args.jobTimeoutMs] - Override the forked-job wall-clock timeout from `configuration.getBackgroundJobsConfig()`. `0` disables it.
    */
-  constructor({configuration, host, port, maxConcurrentForkedJobs, maxConcurrentInlineJobs, forkedChildSigkillGraceMs, heartbeatIntervalMs, jobTimeoutMs} = {}) {
+  constructor({configuration, host, port, maxConcurrentForkedJobs, maxConcurrentInlineJobs, pooledRunnerCount, pooledRunnerMaxJobs, pooledRunnerMaxRssBytes, pooledRunnerMaxLifetimeMs, forkedChildSigkillGraceMs, heartbeatIntervalMs, jobTimeoutMs} = {}) {
     /**
      * Narrows the runtime value to the documented type.
      * @type {Promise<import("../configuration.js").default>} */
@@ -86,6 +109,14 @@ export default class BackgroundJobsWorker {
      * Narrows the runtime value to the documented type.
      * @type {number} */
     this.maxConcurrentForkedJobs = this.maxConcurrentForkedJobsOverride || 4
+    this.pooledRunnerCountOverride = positiveInteger(pooledRunnerCount)
+    this.pooledRunnerMaxJobsOverride = positiveInteger(pooledRunnerMaxJobs)
+    this.pooledRunnerMaxRssBytesOverride = positiveNumber(pooledRunnerMaxRssBytes)
+    this.pooledRunnerMaxLifetimeMsOverride = positiveNumber(pooledRunnerMaxLifetimeMs)
+    this.pooledRunnerCount = this.pooledRunnerCountOverride || 4
+    this.pooledRunnerMaxJobs = this.pooledRunnerMaxJobsOverride || 100
+    this.pooledRunnerMaxRssBytes = this.pooledRunnerMaxRssBytesOverride || 512 * 1024 * 1024
+    this.pooledRunnerMaxLifetimeMs = this.pooledRunnerMaxLifetimeMsOverride || 60 * 60 * 1000
     /**
      * Grace period between SIGTERM and SIGKILL when reaping process runners that
      * outlast a bounded shutdown drain.
@@ -148,6 +179,12 @@ export default class BackgroundJobsWorker {
      * @type {Set<import("node:child_process").ChildProcess>}
      */
     this.inflightProcessChildren = new Set()
+    /** @type {Set<Promise<void>>} */
+    this.inflightPooledJobs = new Set()
+    /** @type {Set<import("node:child_process").ChildProcess>} */
+    this.pooledChildren = new Set()
+    /** @type {Map<import("node:child_process").ChildProcess, {createdAtMs: number, jobsRun: number, payload?: import("./types.js").BackgroundJobPayload & {id: string}, resolve?: (value: void) => void, settling?: boolean}>} */
+    this.pooledChildStates = new Map()
   }
 
   /**
@@ -171,6 +208,11 @@ export default class BackgroundJobsWorker {
 
       this.maxConcurrentForkedJobs = config.maxConcurrentForkedJobs || this.maxConcurrentForkedJobs
     }
+    const poolConfig = this.configuration.getBackgroundJobsConfig()
+    if (typeof this.pooledRunnerCountOverride !== "number") this.pooledRunnerCount = poolConfig.pooledRunnerCount
+    if (typeof this.pooledRunnerMaxJobsOverride !== "number") this.pooledRunnerMaxJobs = poolConfig.pooledRunnerMaxJobs
+    if (typeof this.pooledRunnerMaxRssBytesOverride !== "number") this.pooledRunnerMaxRssBytes = poolConfig.pooledRunnerMaxRssBytes
+    if (typeof this.pooledRunnerMaxLifetimeMsOverride !== "number") this.pooledRunnerMaxLifetimeMs = poolConfig.pooledRunnerMaxLifetimeMs
 
     this.statusReporter = new BackgroundJobsStatusReporter({
       configuration: this.configuration,
@@ -211,6 +253,7 @@ export default class BackgroundJobsWorker {
     }
 
     await this._drainInflight(this.inflightInlineJobs, timeoutMs)
+    await this._drainInflight(this.inflightPooledJobs, timeoutMs)
     await this._drainInflight(this.inflightProcessJobs, timeoutMs)
     await this._terminateProcessChildren()
     // Give in-flight result reports (now decoupled from job slots) a bounded
@@ -311,7 +354,7 @@ export default class BackgroundJobsWorker {
     })
 
     socket.on("connect", () => {
-      jsonSocket.send({type: "hello", role: "worker", supportsHandoffIdReporting: true, supportsHeartbeat: true, workerId: this.workerId})
+      jsonSocket.send({type: "hello", role: "worker", supportsHandoffIdReporting: true, supportsHeartbeat: true, supportsPooled: true, workerId: this.workerId})
       this._sendReadyIfRunning()
       this._startHeartbeat()
     })
@@ -364,6 +407,11 @@ export default class BackgroundJobsWorker {
 
     const executionMode = this._executionModeForPayload(identifiedPayload)
 
+    if (executionMode === "pooled") {
+      this._trackPooledJob(this._runPooledJob(identifiedPayload))
+      return
+    }
+
     if (executionMode !== "inline") {
       this._trackProcessJob(this._startProcessJob({executionMode, payload: identifiedPayload}))
       return
@@ -433,7 +481,9 @@ export default class BackgroundJobsWorker {
 
     if (executionMode) return this._normalizeExecutionMode(executionMode)
 
-    return options.forked === false ? "inline" : "forked"
+    if (options.forked === false) return "inline"
+    if (options.forked === true) return "forked"
+    return "pooled"
   }
 
   /**
@@ -532,17 +582,146 @@ export default class BackgroundJobsWorker {
   _readyMessage() {
     const acceptsProcessJob = this.inflightProcessJobs.size < this.maxConcurrentForkedJobs
     const acceptsInline = this.inflightInlineJobs.size < this.maxConcurrentInlineJobs
+    const acceptsPooled = this.inflightPooledJobs.size < this.pooledRunnerCount
 
-    if (!acceptsProcessJob && !acceptsInline) return null
+    if (!acceptsProcessJob && !acceptsInline && !acceptsPooled) return null
 
     return {
       type: "ready",
       acceptsForked: acceptsProcessJob,
       acceptsInline,
+      acceptsPooled,
       acceptsSpawned: acceptsProcessJob
     }
   }
 
+  /**
+   * Tracks a pooled job and re-advertises capacity.
+   * @param {Promise<void>} pooledJob - Pooled job promise.
+   * @returns {void}
+   */
+  _trackPooledJob(pooledJob) {
+    /** @type {Promise<void>} */
+    let inflight
+    inflight = pooledJob.finally(() => {
+      this.inflightPooledJobs.delete(inflight)
+      if (!this.shouldStop) this._sendReadyIfRunning()
+    })
+    this.inflightPooledJobs.add(inflight)
+    this._sendReadyIfRunning()
+  }
+
+  /**
+   * Runs a payload in an idle pooled child.
+   * @param {import("./types.js").BackgroundJobPayload & {id: string}} payload - Job payload.
+   * @returns {Promise<void>} - Resolves after the durable report.
+   */
+  _runPooledJob(payload) {
+    let child = [...this.pooledChildren].find((candidate) => !this.pooledChildStates.get(candidate)?.payload)
+    if (!child) child = this._createPooledChild()
+    const state = this.pooledChildStates.get(child)
+    if (!state) throw new Error("Pooled runner state missing")
+
+    return new Promise((resolve) => {
+      state.payload = payload
+      state.resolve = resolve
+      try {
+        child.send({type: "job", payload})
+      } catch (error) {
+        this._handlePooledChildFailure({child, error})
+      }
+    })
+  }
+
+  /**
+   * Creates a reusable pooled child.
+   * @returns {import("node:child_process").ChildProcess} - New pooled child.
+   */
+  _createPooledChild() {
+    const configuration = this.configuration
+    if (!configuration) throw new Error("Background jobs worker configuration not initialized")
+    const config = configuration.getBackgroundJobsConfig()
+    const child = fork(POOLED_RUNNER_ENTRY_PATH, [], {
+      cwd: configuration.getDirectory(), execArgv: [], stdio: ["ignore", "ignore", "ignore", "ipc"],
+      env: Object.assign({}, process.env, {VELOCIOUS_ENV: configuration.getEnvironment(), VELOCIOUS_BACKGROUND_JOBS_HOST: config.host, VELOCIOUS_BACKGROUND_JOBS_PORT: `${config.port}`})
+    })
+    this.pooledChildren.add(child)
+    this.inflightProcessChildren.add(child)
+    this.pooledChildStates.set(child, {createdAtMs: Date.now(), jobsRun: 0})
+    child.on("message", (message) => this._handlePooledChildMessage({child, message}))
+    child.once("exit", (code, signal) => this._handlePooledChildFailure({child, error: new Error(`Pooled background job runner exited: code=${code} signal=${signal || "none"}`)}))
+    child.once("error", (error) => this._handlePooledChildFailure({child, error}))
+    return child
+  }
+
+  /**
+   * Handles a pooled child's durable-report acknowledgement.
+   * @param {object} args - Message details.
+   * @param {import("node:child_process").ChildProcess} args.child - Pooled child.
+   * @param {?} args.message - IPC message.
+   * @returns {void}
+   */
+  _handlePooledChildMessage({child, message}) {
+    if (!message || typeof message !== "object") return
+    const record = /** @type {{type?: ?, jobId?: ?, acknowledged?: ?, rssBytes?: ?, error?: ?}} */ (message)
+    const state = this.pooledChildStates.get(child)
+    if (record.type !== "job-outcome" || !state?.payload || record.jobId !== state.payload.id || state.settling) return
+    if (record.acknowledged !== true) {
+      void this._handlePooledChildFailure({child, error: new Error(typeof record.error === "string" ? record.error : "Pooled runner terminal report was not acknowledged")})
+      return
+    }
+    const resolve = state.resolve
+    state.payload = undefined
+    state.resolve = undefined
+    state.jobsRun += 1
+    if (resolve) resolve(undefined)
+    const rssBytes = typeof record.rssBytes === "number" ? record.rssBytes : Number.POSITIVE_INFINITY
+    const runnerAgeMs = Date.now() - state.createdAtMs
+    if (state.jobsRun >= this.pooledRunnerMaxJobs || rssBytes >= this.pooledRunnerMaxRssBytes || runnerAgeMs >= this.pooledRunnerMaxLifetimeMs || this.shouldStop) this._retirePooledChild(child)
+  }
+
+  /**
+   * Retires an idle pooled child.
+   * @param {import("node:child_process").ChildProcess} child - Child process to retire.
+   * @returns {void}
+   */
+  _retirePooledChild(child) {
+    this.pooledChildren.delete(child)
+    this.pooledChildStates.delete(child)
+    this.inflightProcessChildren.delete(child)
+    child.kill("SIGTERM")
+  }
+
+  /**
+   * Removes and reports an unhealthy pooled child.
+   * @param {object} args - Failure details.
+   * @param {import("node:child_process").ChildProcess} args.child - Pooled child.
+   * @param {?} args.error - Failure.
+   * @returns {Promise<void>}
+   */
+  async _handlePooledChildFailure({child, error}) {
+    const state = this.pooledChildStates.get(child)
+    if (state?.settling) return
+    if (state) state.settling = true
+    this.pooledChildren.delete(child)
+    this.inflightProcessChildren.delete(child)
+    if (!state?.payload) {
+      this.pooledChildStates.delete(child)
+      return
+    }
+    const payload = state.payload
+    await this._reportJobResult({
+      jobId: payload.id,
+      status: "failed",
+      error,
+      handoffId: payload.handoffId,
+      handedOffAtMs: payload.handedOffAtMs,
+      workerId: payload.workerId || this.workerId
+    })
+    this.pooledChildStates.delete(child)
+    if (state.resolve) state.resolve(undefined)
+  }
+
   /**
    * Runs run job inline.
    * @param {import("./types.js").BackgroundJobPayload} payload - Payload.

package/src/configuration-types.js

@@ -164,6 +164,10 @@
  *   allowed to keep in flight. Default: `4`. This is a per-worker safety cap;
  *   for workload-shaped limits use per-queue caps (`queues`) instead, which are
  *   enforced cluster-wide and are immune to duplicate worker processes.
+ * @property {number} [pooledRunnerCount] - Number of warm, reusable child runners owned by each worker. Pooled capacity is separate from inline and forked/spawned capacity. Default: `4`.
+ * @property {number} [pooledRunnerMaxJobs] - Number of sequential jobs a pooled child runs before it is replaced, bounding process-level resource accumulation. Default: `100`.
+ * @property {number} [pooledRunnerMaxRssBytes] - RSS bytes after an acknowledged job at which a pooled child is replaced. Default: `536870912` (512 MiB).
+ * @property {number} [pooledRunnerMaxLifetimeMs] - Age after an acknowledged job at which a pooled child is replaced. Default: `3600000` (one hour).
  * @property {Record<string, {maxConcurrent?: number, priority?: number}>} [queues] - Per-queue
  *   concurrency caps and dispatch priorities, Sidekiq-style. A job declares its queue (static
  *   `queue` on the job class, or the `queue` enqueue option; defaults to `"default"`), and

package/src/configuration.js

@@ -1268,12 +1268,20 @@ export default class VelociousConfiguration {
     const envDatabaseIdentifier = process.env.VELOCIOUS_BACKGROUND_JOBS_DATABASE_IDENTIFIER
     const envMaxConcurrentForkedRaw = process.env.VELOCIOUS_BACKGROUND_JOBS_MAX_CONCURRENT_FORKED_JOBS
     const envMaxConcurrentRaw = process.env.VELOCIOUS_BACKGROUND_JOBS_MAX_CONCURRENT_INLINE_JOBS
+    const envPooledRunnerCountRaw = process.env.VELOCIOUS_BACKGROUND_JOBS_POOLED_RUNNER_COUNT
+    const envPooledRunnerMaxJobsRaw = process.env.VELOCIOUS_BACKGROUND_JOBS_POOLED_RUNNER_MAX_JOBS
+    const envPooledRunnerMaxRssBytesRaw = process.env.VELOCIOUS_BACKGROUND_JOBS_POOLED_RUNNER_MAX_RSS_BYTES
+    const envPooledRunnerMaxLifetimeMsRaw = process.env.VELOCIOUS_BACKGROUND_JOBS_POOLED_RUNNER_MAX_LIFETIME_MS
     const envDispatchStrategy = process.env.VELOCIOUS_BACKGROUND_JOBS_DISPATCH_STRATEGY
     const envPollIntervalRaw = process.env.VELOCIOUS_BACKGROUND_JOBS_POLL_INTERVAL_MS
     const envJobTimeoutRaw = process.env.VELOCIOUS_BACKGROUND_JOBS_JOB_TIMEOUT_MS
     const envPort = envPortRaw ? Number(envPortRaw) : undefined
     const envMaxConcurrentForked = envMaxConcurrentForkedRaw ? Number(envMaxConcurrentForkedRaw) : undefined
     const envMaxConcurrent = envMaxConcurrentRaw ? Number(envMaxConcurrentRaw) : undefined
+    const envPooledRunnerCount = envPooledRunnerCountRaw ? Number(envPooledRunnerCountRaw) : undefined
+    const envPooledRunnerMaxJobs = envPooledRunnerMaxJobsRaw ? Number(envPooledRunnerMaxJobsRaw) : undefined
+    const envPooledRunnerMaxRssBytes = envPooledRunnerMaxRssBytesRaw ? Number(envPooledRunnerMaxRssBytesRaw) : undefined
+    const envPooledRunnerMaxLifetimeMs = envPooledRunnerMaxLifetimeMsRaw ? Number(envPooledRunnerMaxLifetimeMsRaw) : undefined
     const envPollInterval = envPollIntervalRaw ? Number(envPollIntervalRaw) : undefined
     const envJobTimeout = envJobTimeoutRaw ? Number(envJobTimeoutRaw) : undefined
     const configured = this._backgroundJobs || {}
@@ -1288,6 +1296,18 @@ export default class VelociousConfiguration {
     const maxConcurrentForkedJobs = typeof configured.maxConcurrentForkedJobs === "number" && configured.maxConcurrentForkedJobs >= 1
       ? configured.maxConcurrentForkedJobs
       : (typeof envMaxConcurrentForked === "number" && Number.isFinite(envMaxConcurrentForked) && envMaxConcurrentForked >= 1 ? envMaxConcurrentForked : 4)
+    const pooledRunnerCount = typeof configured.pooledRunnerCount === "number" && Number.isFinite(configured.pooledRunnerCount) && Number.isInteger(configured.pooledRunnerCount) && configured.pooledRunnerCount >= 1
+      ? configured.pooledRunnerCount
+      : (!("pooledRunnerCount" in configured) && typeof envPooledRunnerCount === "number" && Number.isFinite(envPooledRunnerCount) && Number.isInteger(envPooledRunnerCount) && envPooledRunnerCount >= 1 ? envPooledRunnerCount : 4)
+    const pooledRunnerMaxJobs = typeof configured.pooledRunnerMaxJobs === "number" && Number.isFinite(configured.pooledRunnerMaxJobs) && Number.isInteger(configured.pooledRunnerMaxJobs) && configured.pooledRunnerMaxJobs >= 1
+      ? configured.pooledRunnerMaxJobs
+      : (!("pooledRunnerMaxJobs" in configured) && typeof envPooledRunnerMaxJobs === "number" && Number.isFinite(envPooledRunnerMaxJobs) && Number.isInteger(envPooledRunnerMaxJobs) && envPooledRunnerMaxJobs >= 1 ? envPooledRunnerMaxJobs : 100)
+    const pooledRunnerMaxRssBytes = typeof configured.pooledRunnerMaxRssBytes === "number" && Number.isFinite(configured.pooledRunnerMaxRssBytes) && configured.pooledRunnerMaxRssBytes >= 1
+      ? configured.pooledRunnerMaxRssBytes
+      : (!("pooledRunnerMaxRssBytes" in configured) && typeof envPooledRunnerMaxRssBytes === "number" && Number.isFinite(envPooledRunnerMaxRssBytes) && envPooledRunnerMaxRssBytes >= 1 ? envPooledRunnerMaxRssBytes : 512 * 1024 * 1024)
+    const pooledRunnerMaxLifetimeMs = typeof configured.pooledRunnerMaxLifetimeMs === "number" && Number.isFinite(configured.pooledRunnerMaxLifetimeMs) && configured.pooledRunnerMaxLifetimeMs >= 1
+      ? configured.pooledRunnerMaxLifetimeMs
+      : (!("pooledRunnerMaxLifetimeMs" in configured) && typeof envPooledRunnerMaxLifetimeMs === "number" && Number.isFinite(envPooledRunnerMaxLifetimeMs) && envPooledRunnerMaxLifetimeMs >= 1 ? envPooledRunnerMaxLifetimeMs : 60 * 60 * 1000)
     const dispatchStrategyRaw = configured.dispatchStrategy || envDispatchStrategy
     const dispatchStrategy = dispatchStrategyRaw === "polling" ? "polling" : "beacon"
     const pollIntervalMs = typeof configured.pollIntervalMs === "number" && configured.pollIntervalMs >= 1
@@ -1316,7 +1336,7 @@ export default class VelociousConfiguration {
         : 60 * 60 * 1000
     }
 
-    return {host, port, databaseIdentifier, maxConcurrentForkedJobs, maxConcurrentInlineJobs, dispatchStrategy, pollIntervalMs, queues, jobTimeoutMs, retention}
+    return {host, port, databaseIdentifier, maxConcurrentForkedJobs, maxConcurrentInlineJobs, pooledRunnerCount, pooledRunnerMaxJobs, pooledRunnerMaxRssBytes, pooledRunnerMaxLifetimeMs, dispatchStrategy, pollIntervalMs, queues, jobTimeoutMs, retention}
   }
 
   /**