velocious 1.0.686 → 1.0.688

package/build/src/http-server/client/serve-file.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Serves a static file from `root` directory to the response as a
+ * length-determined body (no chunked transfer-encoding).
+ *
+ * This is the proxy-safe alternative to `response.setFilePath()` /
+ * `response.stream()`: the file is read into memory and sent with an
+ * explicit `Content-Length` header, which avoids issues with proxies
+ * (e.g. Rollbridge) that do not support chunked transfer encoding.
+ * @param {import("./response.js").default} response
+ *   The HTTP response to write to.
+ * @param {string} root - Absolute directory path that files must live under.
+ * @param {string} name - File name (or relative path) to serve from within `root`.
+ * @param {object} [options] - Serving options.
+ * @param {string} [options.contentType] - MIME type to set on the response.
+ * @param {string} [options.cacheControl] - Value for the `Cache-Control` header.
+ * @returns {Promise<boolean>} - `true` if the file was served, `false` if the
+ *   file was not found or the name resolved outside the root (404 set in both cases).
+ */
+export default function serveFile(response: import("./response.js").default, root: string, name: string, options?: {
+    contentType?: string;
+    cacheControl?: string;
+}): Promise<boolean>;
+//# sourceMappingURL=serve-file.d.ts.map

package/build/src/http-server/client/serve-file.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"serve-file.d.ts","sourceRoot":"","sources":["../../../../src/http-server/client/serve-file.js"],"names":[],"mappings":"AAKA;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAA8B,SAAS,CAAC,QAAQ,EAVrC,OAAO,eAAe,EAAE,OAUa,EAAE,IAAI,EAR3C,MAQ2C,EAAE,IAAI,EAPjD,MAOiD,EAAE,OAAO,AANlE,CAGA,EAFA;IAAyB,WAAW,AAApC,CACA,EADQ,MAAM,CACd;IAAyB,YAAY,AAArC,CACA,EADQ,MAAM,CACd;CAGuE,GAH7D,OAAO,CAAC,OAAO,CAAC,CA2C5B"}

package/build/src/http-server/client/serve-file.js

@@ -0,0 +1,56 @@
+// @ts-check
+import fs from "node:fs/promises";
+import path from "node:path";
+/**
+ * Serves a static file from `root` directory to the response as a
+ * length-determined body (no chunked transfer-encoding).
+ *
+ * This is the proxy-safe alternative to `response.setFilePath()` /
+ * `response.stream()`: the file is read into memory and sent with an
+ * explicit `Content-Length` header, which avoids issues with proxies
+ * (e.g. Rollbridge) that do not support chunked transfer encoding.
+ * @param {import("./response.js").default} response
+ *   The HTTP response to write to.
+ * @param {string} root - Absolute directory path that files must live under.
+ * @param {string} name - File name (or relative path) to serve from within `root`.
+ * @param {object} [options] - Serving options.
+ * @param {string} [options.contentType] - MIME type to set on the response.
+ * @param {string} [options.cacheControl] - Value for the `Cache-Control` header.
+ * @returns {Promise<boolean>} - `true` if the file was served, `false` if the
+ *   file was not found or the name resolved outside the root (404 set in both cases).
+ */
+export default async function serveFile(response, root, name, options = {}) {
+    const { contentType, cacheControl } = options;
+    // Reject empty or null names.
+    if (!name || typeof name !== "string") {
+        response.setStatus(404);
+        return false;
+    }
+    // Resolve the target path and verify it stays within root.
+    const resolvedRoot = path.resolve(root);
+    const targetPath = path.resolve(resolvedRoot, name);
+    // Path containment check: the resolved target must be inside root.
+    if (targetPath !== resolvedRoot && !targetPath.startsWith(resolvedRoot + path.sep)) {
+        response.setStatus(404);
+        return false;
+    }
+    // lstat to reject symlinks and confirm the path is a regular file.
+    let stat;
+    try {
+        stat = await fs.lstat(targetPath);
+    }
+    catch {
+        response.setStatus(404);
+        return false;
+    }
+    if (!stat.isFile() || stat.isSymbolicLink()) {
+        response.setStatus(404);
+        return false;
+    }
+    const data = await fs.readFile(targetPath);
+    response.setBody(data);
+    response.setHeader("Content-Type", contentType || "application/octet-stream");
+    response.setHeader("Cache-Control", cacheControl || "no-store");
+    return true;
+}
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoic2VydmUtZmlsZS5qcyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4uLy4uLy4uLy4uL3NyYy9odHRwLXNlcnZlci9jbGllbnQvc2VydmUtZmlsZS5qcyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiQUFBQSxZQUFZO0FBRVosT0FBTyxFQUFFLE1BQU0sa0JBQWtCLENBQUE7QUFDakMsT0FBTyxJQUFJLE1BQU0sV0FBVyxDQUFBO0FBRTVCOzs7Ozs7Ozs7Ozs7Ozs7OztHQWlCRztBQUNILE1BQU0sQ0FBQyxPQUFPLENBQUMsS0FBSyxVQUFVLFNBQVMsQ0FBQyxRQUFRLEVBQUUsSUFBSSxFQUFFLElBQUksRUFBRSxPQUFPLEdBQUcsRUFBRTtJQUN4RSxNQUFNLEVBQUMsV0FBVyxFQUFFLFlBQVksRUFBQyxHQUFHLE9BQU8sQ0FBQTtJQUUzQyw4QkFBOEI7SUFDOUIsSUFBSSxDQUFDLElBQUksSUFBSSxPQUFPLElBQUksS0FBSyxRQUFRLEVBQUUsQ0FBQztRQUN0QyxRQUFRLENBQUMsU0FBUyxDQUFDLEdBQUcsQ0FBQyxDQUFBO1FBQ3ZCLE9BQU8sS0FBSyxDQUFBO0lBQ2QsQ0FBQztJQUVELDJEQUEyRDtJQUMzRCxNQUFNLFlBQVksR0FBRyxJQUFJLENBQUMsT0FBTyxDQUFDLElBQUksQ0FBQyxDQUFBO0lBQ3ZDLE1BQU0sVUFBVSxHQUFHLElBQUksQ0FBQyxPQUFPLENBQUMsWUFBWSxFQUFFLElBQUksQ0FBQyxDQUFBO0lBRW5ELG1FQUFtRTtJQUNuRSxJQUFJLFVBQVUsS0FBSyxZQUFZLElBQUksQ0FBQyxVQUFVLENBQUMsVUFBVSxDQUFDLFlBQVksR0FBRyxJQUFJLENBQUMsR0FBRyxDQUFDLEVBQUUsQ0FBQztRQUNuRixRQUFRLENBQUMsU0FBUyxDQUFDLEdBQUcsQ0FBQyxDQUFBO1FBQ3ZCLE9BQU8sS0FBSyxDQUFBO0lBQ2QsQ0FBQztJQUVELG1FQUFtRTtJQUNuRSxJQUFJLElBQUksQ0FBQTtJQUNSLElBQUksQ0FBQztRQUNILElBQUksR0FBRyxNQUFNLEVBQUUsQ0FBQyxLQUFLLENBQUMsVUFBVSxDQUFDLENBQUE7SUFDbkMsQ0FBQztJQUFDLE1BQU0sQ0FBQztRQUNQLFFBQVEsQ0FBQyxTQUFTLENBQUMsR0FBRyxDQUFDLENBQUE7UUFDdkIsT0FBTyxLQUFLLENBQUE7SUFDZCxDQUFDO0lBRUQsSUFBSSxDQUFDLElBQUksQ0FBQyxNQUFNLEVBQUUsSUFBSSxJQUFJLENBQUMsY0FBYyxFQUFFLEVBQUUsQ0FBQztRQUM1QyxRQUFRLENBQUMsU0FBUyxDQUFDLEdBQUcsQ0FBQyxDQUFBO1FBQ3ZCLE9BQU8sS0FBSyxDQUFBO0lBQ2QsQ0FBQztJQUVELE1BQU0sSUFBSSxHQUFHLE1BQU0sRUFBRSxDQUFDLFFBQVEsQ0FBQyxVQUFVLENBQUMsQ0FBQTtJQUUxQyxRQUFRLENBQUMsT0FBTyxDQUFDLElBQUksQ0FBQyxDQUFBO0lBQ3RCLFFBQVEsQ0FBQyxTQUFTLENBQUMsY0FBYyxFQUFFLFdBQVcsSUFBSSwwQkFBMEIsQ0FBQyxDQUFBO0lBQzdFLFFBQVEsQ0FBQyxTQUFTLENBQUMsZUFBZSxFQUFFLFlBQVksSUFBSSxVQUFVLENBQUMsQ0FBQTtJQUUvRCxPQUFPLElBQUksQ0FBQTtBQUNiLENBQUMiLCJzb3VyY2VzQ29udGVudCI6WyIvLyBAdHMtY2hlY2tcblxuaW1wb3J0IGZzIGZyb20gXCJub2RlOmZzL3Byb21pc2VzXCJcbmltcG9ydCBwYXRoIGZyb20gXCJub2RlOnBhdGhcIlxuXG4vKipcbiAqIFNlcnZlcyBhIHN0YXRpYyBmaWxlIGZyb20gYHJvb3RgIGRpcmVjdG9yeSB0byB0aGUgcmVzcG9uc2UgYXMgYVxuICogbGVuZ3RoLWRldGVybWluZWQgYm9keSAobm8gY2h1bmtlZCB0cmFuc2Zlci1lbmNvZGluZykuXG4gKlxuICogVGhpcyBpcyB0aGUgcHJveHktc2FmZSBhbHRlcm5hdGl2ZSB0byBgcmVzcG9uc2Uuc2V0RmlsZVBhdGgoKWAgL1xuICogYHJlc3BvbnNlLnN0cmVhbSgpYDogdGhlIGZpbGUgaXMgcmVhZCBpbnRvIG1lbW9yeSBhbmQgc2VudCB3aXRoIGFuXG4gKiBleHBsaWNpdCBgQ29udGVudC1MZW5ndGhgIGhlYWRlciwgd2hpY2ggYXZvaWRzIGlzc3VlcyB3aXRoIHByb3hpZXNcbiAqIChlLmcuIFJvbGxicmlkZ2UpIHRoYXQgZG8gbm90IHN1cHBvcnQgY2h1bmtlZCB0cmFuc2ZlciBlbmNvZGluZy5cbiAqIEBwYXJhbSB7aW1wb3J0KFwiLi9yZXNwb25zZS5qc1wiKS5kZWZhdWx0fSByZXNwb25zZVxuICogICBUaGUgSFRUUCByZXNwb25zZSB0byB3cml0ZSB0by5cbiAqIEBwYXJhbSB7c3RyaW5nfSByb290IC0gQWJzb2x1dGUgZGlyZWN0b3J5IHBhdGggdGhhdCBmaWxlcyBtdXN0IGxpdmUgdW5kZXIuXG4gKiBAcGFyYW0ge3N0cmluZ30gbmFtZSAtIEZpbGUgbmFtZSAob3IgcmVsYXRpdmUgcGF0aCkgdG8gc2VydmUgZnJvbSB3aXRoaW4gYHJvb3RgLlxuICogQHBhcmFtIHtvYmplY3R9IFtvcHRpb25zXSAtIFNlcnZpbmcgb3B0aW9ucy5cbiAqIEBwYXJhbSB7c3RyaW5nfSBbb3B0aW9ucy5jb250ZW50VHlwZV0gLSBNSU1FIHR5cGUgdG8gc2V0IG9uIHRoZSByZXNwb25zZS5cbiAqIEBwYXJhbSB7c3RyaW5nfSBbb3B0aW9ucy5jYWNoZUNvbnRyb2xdIC0gVmFsdWUgZm9yIHRoZSBgQ2FjaGUtQ29udHJvbGAgaGVhZGVyLlxuICogQHJldHVybnMge1Byb21pc2U8Ym9vbGVhbj59IC0gYHRydWVgIGlmIHRoZSBmaWxlIHdhcyBzZXJ2ZWQsIGBmYWxzZWAgaWYgdGhlXG4gKiAgIGZpbGUgd2FzIG5vdCBmb3VuZCBvciB0aGUgbmFtZSByZXNvbHZlZCBvdXRzaWRlIHRoZSByb290ICg0MDQgc2V0IGluIGJvdGggY2FzZXMpLlxuICovXG5leHBvcnQgZGVmYXVsdCBhc3luYyBmdW5jdGlvbiBzZXJ2ZUZpbGUocmVzcG9uc2UsIHJvb3QsIG5hbWUsIG9wdGlvbnMgPSB7fSkge1xuICBjb25zdCB7Y29udGVudFR5cGUsIGNhY2hlQ29udHJvbH0gPSBvcHRpb25zXG5cbiAgLy8gUmVqZWN0IGVtcHR5IG9yIG51bGwgbmFtZXMuXG4gIGlmICghbmFtZSB8fCB0eXBlb2YgbmFtZSAhPT0gXCJzdHJpbmdcIikge1xuICAgIHJlc3BvbnNlLnNldFN0YXR1cyg0MDQpXG4gICAgcmV0dXJuIGZhbHNlXG4gIH1cblxuICAvLyBSZXNvbHZlIHRoZSB0YXJnZXQgcGF0aCBhbmQgdmVyaWZ5IGl0IHN0YXlzIHdpdGhpbiByb290LlxuICBjb25zdCByZXNvbHZlZFJvb3QgPSBwYXRoLnJlc29sdmUocm9vdClcbiAgY29uc3QgdGFyZ2V0UGF0aCA9IHBhdGgucmVzb2x2ZShyZXNvbHZlZFJvb3QsIG5hbWUpXG5cbiAgLy8gUGF0aCBjb250YWlubWVudCBjaGVjazogdGhlIHJlc29sdmVkIHRhcmdldCBtdXN0IGJlIGluc2lkZSByb290LlxuICBpZiAodGFyZ2V0UGF0aCAhPT0gcmVzb2x2ZWRSb290ICYmICF0YXJnZXRQYXRoLnN0YXJ0c1dpdGgocmVzb2x2ZWRSb290ICsgcGF0aC5zZXApKSB7XG4gICAgcmVzcG9uc2Uuc2V0U3RhdHVzKDQwNClcbiAgICByZXR1cm4gZmFsc2VcbiAgfVxuXG4gIC8vIGxzdGF0IHRvIHJlamVjdCBzeW1saW5rcyBhbmQgY29uZmlybSB0aGUgcGF0aCBpcyBhIHJlZ3VsYXIgZmlsZS5cbiAgbGV0IHN0YXRcbiAgdHJ5IHtcbiAgICBzdGF0ID0gYXdhaXQgZnMubHN0YXQodGFyZ2V0UGF0aClcbiAgfSBjYXRjaCB7XG4gICAgcmVzcG9uc2Uuc2V0U3RhdHVzKDQwNClcbiAgICByZXR1cm4gZmFsc2VcbiAgfVxuXG4gIGlmICghc3RhdC5pc0ZpbGUoKSB8fCBzdGF0LmlzU3ltYm9saWNMaW5rKCkpIHtcbiAgICByZXNwb25zZS5zZXRTdGF0dXMoNDA0KVxuICAgIHJldHVybiBmYWxzZVxuICB9XG5cbiAgY29uc3QgZGF0YSA9IGF3YWl0IGZzLnJlYWRGaWxlKHRhcmdldFBhdGgpXG5cbiAgcmVzcG9uc2Uuc2V0Qm9keShkYXRhKVxuICByZXNwb25zZS5zZXRIZWFkZXIoXCJDb250ZW50LVR5cGVcIiwgY29udGVudFR5cGUgfHwgXCJhcHBsaWNhdGlvbi9vY3RldC1zdHJlYW1cIilcbiAgcmVzcG9uc2Uuc2V0SGVhZGVyKFwiQ2FjaGUtQ29udHJvbFwiLCBjYWNoZUNvbnRyb2wgfHwgXCJuby1zdG9yZVwiKVxuXG4gIHJldHVybiB0cnVlXG59XG4iXX0=

package/package.json

@@ -3,7 +3,7 @@
     "velocious": "build/bin/velocious.js"
   },
   "name": "velocious",
-  "version": "1.0.686",
+  "version": "1.0.688",
   "main": "build/index.js",
   "types": "build/index.d.ts",
   "files": [

package/src/background-jobs/main.js

@@ -1,5 +1,6 @@
 // @ts-check
 
+import timeout, { TimeoutError } from "awaitery/build/timeout.js"
 import { randomUUID } from "crypto"
 import net from "net"
 import JsonSocket from "./json-socket.js"
@@ -146,6 +147,7 @@ export default class BackgroundJobsMain {
     this.port = typeof port === "number" ? port : config.port
     this.dispatchStrategy = config.dispatchStrategy
     this.pollIntervalMs = config.pollIntervalMs
+    this.drainStoreOperationTimeoutMs = config.drainStoreOperationTimeoutMs
     this.retention = config.retention
     // A worker that stops sending anything (heartbeat/ready/report) for this
     // long is treated as wedged/dead: its leases are released and it is dropped.
@@ -2064,10 +2066,49 @@ export default class BackgroundJobsMain {
       return false
     } catch (error) {
       this.logger.error(() => ["Background jobs drain failed:", error])
+      if (error instanceof TimeoutError) this._reportDrainStallError(error)
       return true
     }
   }
 
+  /**
+   * Bounds one drain-critical store operation so a store call that never
+   * settles rejects into the drain error/retry path instead of stalling the
+   * coalesced drain and every later dispatch queued behind it.
+   * @template T
+   * @param {string} operation - Operation label for the timeout error.
+   * @param {() => Promise<T>} callback - Drain store operation.
+   * @returns {Promise<T>} - Operation result.
+   */
+  async _boundedDrainStoreOperation(operation, callback) {
+    return await timeout({
+      errorMessage: `Background jobs drain store operation timed out after ${this.drainStoreOperationTimeoutMs}ms: ${operation}`,
+      timeout: this.drainStoreOperationTimeoutMs
+    }, callback)
+  }
+
+  /**
+   * Surfaces a drain pass whose store operation never settled. The bounded
+   * store timeout keeps dispatch moving through the error-retry path; this
+   * report makes the stall observable for process-level bug reporters.
+   * @param {Error} error - Drain stall failure.
+   * @returns {void}
+   */
+  _reportDrainStallError(error) {
+    const payload = {
+      context: {
+        stage: "background-jobs-drain-stall",
+        drainStoreOperationTimeoutMs: this.drainStoreOperationTimeoutMs,
+        dispatchStrategy: this.dispatchStrategy
+      },
+      error
+    }
+    const errorEvents = this.configuration.getErrorEvents()
+
+    errorEvents.emit("framework-error", payload)
+    errorEvents.emit("all-error", {...payload, errorType: "framework-error"})
+  }
+
   /**
    * Arms a one-shot `setTimeout` to retry `_drain` after a transient
    * failure. Idempotent — repeated calls while a retry is already
@@ -2127,7 +2168,7 @@ export default class BackgroundJobsMain {
    */
   async _drainOnce() {
     while (this.readyWorkers.size > 0 && !this._stopped && this.lifecycleState === "active" && this._activeOwnershipReady) {
-      const job = await this.nextAvailableJobForReadyWorkers()
+      const job = await this._boundedDrainStoreOperation("next-available-job", async () => await this.nextAvailableJobForReadyWorkers())
       if (!job) return
 
       const worker = this.readyWorkerForJob(job)
@@ -2138,13 +2179,13 @@ export default class BackgroundJobsMain {
       let handoff
 
       try {
-        handoff = await this.store.markHandedOff({handoffId: requestedHandoffId, jobId: job.id, workerId: worker.workerId})
+        handoff = await this._boundedDrainStoreOperation("mark-handed-off", async () => await this.store.markHandedOff({handoffId: requestedHandoffId, jobId: job.id, workerId: worker.workerId}))
       } catch (error) {
         this._rememberHandoffRecovery({handoffId: requestedHandoffId, jobId: job.id})
         this._restoreWorkerAdmission({...admission, worker})
 
         try {
-          await this._recoverHandoff({handoffId: requestedHandoffId, jobId: job.id})
+          await this._boundedDrainStoreOperation("recover-handoff", async () => await this._recoverHandoff({handoffId: requestedHandoffId, jobId: job.id}))
         } catch (recoveryError) {
           this._reportHandoffRecoveryError({error: recoveryError, handoffId: requestedHandoffId, jobId: job.id})
         }
@@ -2164,7 +2205,7 @@ export default class BackgroundJobsMain {
       if (!handoffs || !this.workers.has(worker) || worker.isDraining || this.lifecycleState !== "active" || !this._activeOwnershipReady) {
         this._rememberHandoffRecovery({handoffId: handoff.handoffId, jobId: job.id})
         try {
-          await this._recoverHandoff({handoffId: handoff.handoffId, jobId: job.id})
+          await this._boundedDrainStoreOperation("recover-handoff", async () => await this._recoverHandoff({handoffId: handoff.handoffId, jobId: job.id}))
         } catch (recoveryError) {
           this._reportHandoffRecoveryError({error: recoveryError, handoffId: handoff.handoffId, jobId: job.id})
           throw recoveryError

package/src/background-jobs/worker.js

@@ -1147,6 +1147,24 @@ export default class BackgroundJobsWorker {
     return Math.max(0, this.pooledRunnerCount - this.pooledChildren.size)
   }
 
+  /**
+   * Counts live children still able to run new work. The pool must always
+   * keep — or restore, through the bounded over-cap liveness replacement — at
+   * least one non-retiring child: with every live child retiring, advertised
+   * capacity is zero for the entire drain window, which can stretch to the
+   * longest in-flight job, and dispatch silently stalls.
+   * @returns {number} - Number of non-retiring pooled children.
+   */
+  _nonRetiringPooledChildCount() {
+    let count = 0
+
+    for (const state of this.pooledChildStates.values()) {
+      if (!state.retiring) count += 1
+    }
+
+    return count
+  }
+
   /**
    * Resolves once a non-retiring pooled child has a free concurrency slot or the
    * pool may spawn a new one. Pooled jobs admitted while the pool is at its
@@ -1358,13 +1376,18 @@ export default class BackgroundJobsWorker {
    * Creates a reusable pooled child, enforcing the hard cap on total live
    * children (working + draining). Returns undefined when the cap is already
    * met — the only way a new child may exist is a slot being open, so the
-   * caller re-checks and waits again.
+   * caller re-checks and waits again. `allowOverCap` is reserved for the
+   * bounded liveness replacement: at most one child beyond the cap may exist,
+   * and only when every other live child is already retiring (see
+   * `_beginRetirePooledChild` for the gate).
+   * @param {object} [args] - Spawn options.
+   * @param {boolean} [args.allowOverCap] - Allow one over-cap spawn for the liveness replacement.
    * @returns {import("node:child_process").ChildProcess | undefined} - The new child, or undefined when the pool is at its cap.
    */
-  _createPooledChild() {
+  _createPooledChild({allowOverCap = false} = {}) {
     const configuration = this.configuration
     if (!configuration) throw new Error("Background jobs worker configuration not initialized")
-    if (this.pooledChildren.size >= this.pooledRunnerCount) return undefined
+    if (!allowOverCap && this.pooledChildren.size >= this.pooledRunnerCount) return undefined
     const child = fork(POOLED_RUNNER_ENTRY_PATH, [], {
       cwd: configuration.getDirectory(), execArgv: [], stdio: ["ignore", "ignore", "ignore", "ipc"],
       env: Object.assign({}, process.env, this._childBackgroundJobsEnvironment())
@@ -1577,10 +1600,19 @@ export default class BackgroundJobsWorker {
    * cap — eagerly spawns a single replacement (1-for-1) so its capacity is
    * restored immediately without waiting for it to finish draining. The
    * replacement spawn is gated by the cap (the retiring child still counts as
-   * live until it exits), so a full pool simply defers the replacement to the
-   * retiring child's drain instead of spawning over capacity. The retiring
-   * child stops receiving new jobs and is terminated only once its in-flight
-   * set drains, so a long-running job (e.g. a build) is never cut off.
+   * live until it exits), so a full pool defers the replacement to the drain
+   * path. One bounded exception keeps the pool from ever advertising zero
+   * capacity: when this mark leaves no non-retiring child, a single liveness
+   * replacement spawns over the cap — live children stay bounded at
+   * `pooledRunnerCount + 1`, and the extra child is absorbed by the next
+   * draining exit. Without it, a full retirement wave (e.g. every child
+   * crossing the peak-RSS threshold after the same memory burst) silently
+   * removes all pooled capacity for the whole drain window, which can stretch
+   * to the longest in-flight job. When even the liveness spawn is unavailable
+   * (an over-cap child is already draining), the starvation is logged so it is
+   * visible instead of silent. The retiring child stops receiving new jobs and
+   * is terminated only once its in-flight set drains, so a long-running job
+   * (e.g. a build) is never cut off.
    * @param {import("node:child_process").ChildProcess} child - Child to retire.
    * @returns {void}
    */
@@ -1592,8 +1624,55 @@ export default class BackgroundJobsWorker {
     // Best-effort pre-warm: skip when stopping (no new work) or before the
     // worker is initialized (no configuration to fork a child from). The cap
     // inside _createPooledChild refuses the spawn while the pool is full, in
-    // which case the replacement is deferred to the drain path.
-    if (!this.shouldStop && this.configuration) this._createPooledChild()
+    // which case the bounded liveness replacement below takes over.
+    if (this.shouldStop || !this.configuration) return
+
+    if (this._createPooledChild()) return
+    if (this._nonRetiringPooledChildCount() > 0) return
+
+    // Liveness replacement: this mark emptied the working pool, so advertised
+    // capacity would be zero until a draining child exits. Spawn one
+    // replacement over the hard cap (bounded: the gate admits it only when the
+    // live count is at most the cap, so at most one over-cap child exists and
+    // the next draining exit absorbs it).
+    if (this.pooledChildren.size <= this.pooledRunnerCount) {
+      const livenessChild = this._createPooledChild({allowOverCap: true})
+
+      if (livenessChild) {
+        this._logPooledCapacityEvent("pooled-capacity-liveness-spawn")
+        return
+      }
+    }
+
+    // An over-cap child is already draining: the pool waits for the next
+    // draining exit, which frees a cap slot for a lazy replacement. Log it so
+    // this bounded starvation is not silent.
+    this._logPooledCapacityEvent("pooled-capacity-starved")
+  }
+
+  /**
+   * Logs one compact pooled-capacity event to the worker's own stderr (the
+   * surface that reaches the production log). Used by the bounded liveness
+   * replacement in `_beginRetirePooledChild`: the spawn that keeps dispatch
+   * alive through a full retirement wave, or the bounded starvation when an
+   * over-cap child is already draining and the pool must wait for an exit.
+   * @param {"pooled-capacity-liveness-spawn" | "pooled-capacity-starved"} event - Event name.
+   * @returns {void}
+   */
+  _logPooledCapacityEvent(event) {
+    let retiringChildren = 0
+
+    for (const state of this.pooledChildStates.values()) {
+      if (state.retiring) retiringChildren += 1
+    }
+
+    console.error(JSON.stringify({
+      event,
+      liveChildren: this.pooledChildren.size,
+      retiringChildren,
+      cap: this.pooledRunnerCount,
+      concurrency: this.pooledRunnerConcurrency
+    }))
   }
 
   /**

package/src/configuration-types.js

@@ -224,6 +224,14 @@
  *   to restore the legacy fixed-interval poll.
  * @property {number} [pollIntervalMs] - Poll interval in milliseconds. Only used
  *   when `dispatchStrategy === "polling"`. Default: `1000`.
+ * @property {number} [drainStoreOperationTimeoutMs] - Bounds one drain-critical
+ *   store operation in the main process: the queued-job lookup, the durable
+ *   handoff claim, and handoff-recovery transitions. A store call that never
+ *   settles (wedged DB connection, lost acknowledgement) would otherwise freeze
+ *   the coalesced drain and every later dispatch queued behind it until the
+ *   process is killed; on timeout the drain fails into its existing
+ *   error/retry path and the stall is reported as a framework error.
+ *   Default: `60000`.
  * @property {number | null} [jobTimeoutMs] - Wall-clock backstop, in ms, for a
  *   `"forked"` job runner. A forked job still running after this is terminated
  *   (SIGTERM, then SIGKILL after the reaping grace) and reported failed, so a

package/src/configuration.js

@@ -1687,6 +1687,9 @@ export default class VelociousConfiguration {
     const pollIntervalMs = typeof configured.pollIntervalMs === "number" && configured.pollIntervalMs >= 1
       ? configured.pollIntervalMs
       : (typeof envPollInterval === "number" && Number.isFinite(envPollInterval) && envPollInterval >= 1 ? envPollInterval : 1000)
+    const drainStoreOperationTimeoutMs = typeof configured.drainStoreOperationTimeoutMs === "number" && configured.drainStoreOperationTimeoutMs >= 1
+      ? configured.drainStoreOperationTimeoutMs
+      : 60_000
     const queues = configured.queues && typeof configured.queues === "object" ? configured.queues : {}
     // An explicit config value wins over the env var — including `null`/`0`,
     // which disable the backstop even when the environment sets a default.
@@ -1712,7 +1715,7 @@ export default class VelociousConfiguration {
 
     const jobClasses = this.getBackgroundJobClasses()
 
-    return {host, port, databaseIdentifier, maxConcurrentForkedJobs, maxConcurrentInlineJobs, mode, pooledRunnerCount, pooledRunnerConcurrency, pooledRunnerMaxJobs, pooledRunnerMaxRssBytes, pooledRunnerMaxLifetimeMs, dispatchStrategy, pollIntervalMs, queues, jobClasses, jobTimeoutMs, retention, generationId, initialGenerationState, lifecycleSocketPath}
+    return {host, port, databaseIdentifier, maxConcurrentForkedJobs, maxConcurrentInlineJobs, mode, pooledRunnerCount, pooledRunnerConcurrency, pooledRunnerMaxJobs, pooledRunnerMaxRssBytes, pooledRunnerMaxLifetimeMs, dispatchStrategy, pollIntervalMs, drainStoreOperationTimeoutMs, queues, jobClasses, jobTimeoutMs, retention, generationId, initialGenerationState, lifecycleSocketPath}
   }
 
   /**

package/src/http-server/client/serve-file.js

@@ -0,0 +1,64 @@
+// @ts-check
+
+import fs from "node:fs/promises"
+import path from "node:path"
+
+/**
+ * Serves a static file from `root` directory to the response as a
+ * length-determined body (no chunked transfer-encoding).
+ *
+ * This is the proxy-safe alternative to `response.setFilePath()` /
+ * `response.stream()`: the file is read into memory and sent with an
+ * explicit `Content-Length` header, which avoids issues with proxies
+ * (e.g. Rollbridge) that do not support chunked transfer encoding.
+ * @param {import("./response.js").default} response
+ *   The HTTP response to write to.
+ * @param {string} root - Absolute directory path that files must live under.
+ * @param {string} name - File name (or relative path) to serve from within `root`.
+ * @param {object} [options] - Serving options.
+ * @param {string} [options.contentType] - MIME type to set on the response.
+ * @param {string} [options.cacheControl] - Value for the `Cache-Control` header.
+ * @returns {Promise<boolean>} - `true` if the file was served, `false` if the
+ *   file was not found or the name resolved outside the root (404 set in both cases).
+ */
+export default async function serveFile(response, root, name, options = {}) {
+  const {contentType, cacheControl} = options
+
+  // Reject empty or null names.
+  if (!name || typeof name !== "string") {
+    response.setStatus(404)
+    return false
+  }
+
+  // Resolve the target path and verify it stays within root.
+  const resolvedRoot = path.resolve(root)
+  const targetPath = path.resolve(resolvedRoot, name)
+
+  // Path containment check: the resolved target must be inside root.
+  if (targetPath !== resolvedRoot && !targetPath.startsWith(resolvedRoot + path.sep)) {
+    response.setStatus(404)
+    return false
+  }
+
+  // lstat to reject symlinks and confirm the path is a regular file.
+  let stat
+  try {
+    stat = await fs.lstat(targetPath)
+  } catch {
+    response.setStatus(404)
+    return false
+  }
+
+  if (!stat.isFile() || stat.isSymbolicLink()) {
+    response.setStatus(404)
+    return false
+  }
+
+  const data = await fs.readFile(targetPath)
+
+  response.setBody(data)
+  response.setHeader("Content-Type", contentType || "application/octet-stream")
+  response.setHeader("Cache-Control", cacheControl || "no-store")
+
+  return true
+}