velocious 1.0.690 → 1.0.691

package/package.json

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

package/src/background-jobs/worker.js

@@ -1617,7 +1617,11 @@ export default class BackgroundJobsWorker {
    * whole drain window, which can stretch to the longest in-flight job. 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.
+   * off. When the pool already carries its bounded over-cap child, retiring
+   * the last working child is deferred instead of emptying the working pool:
+   * the child keeps serving and a later observation retries the retirement
+   * once a draining exit has freed a cap slot, so advertised capacity cannot
+   * collapse to zero inside a wave.
    * @param {import("node:child_process").ChildProcess} child - Child to retire.
    * @returns {void}
    */
@@ -1625,6 +1629,17 @@ export default class BackgroundJobsWorker {
     const state = this.pooledChildStates.get(child)
     if (!state || state.retiring) return
 
+    // Retiring the last non-retiring child while the pool already carries its
+    // bounded over-cap child would leave advertised capacity at zero until the
+    // next draining exit — up to the longest in-flight job (tens of minutes
+    // with builds), stalling dispatch cluster-wide. Defer this retirement
+    // instead: the child keeps serving and a later observation retries once a
+    // drain has freed a cap slot for its replacement.
+    if (!this.shouldStop && this.configuration && this._nonRetiringPooledChildCount() <= 1 && this.pooledChildren.size > this.pooledRunnerCount) {
+      this._logPooledCapacityEvent("pooled-capacity-retirement-deferred")
+      return
+    }
+
     state.retiring = true
     // 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
@@ -1688,9 +1703,11 @@ export default class BackgroundJobsWorker {
    * surface that reaches the production log). Used by the bounded liveness
    * replacement in `_ensureNonRetiringChild`: the spawn that keeps dispatch
    * alive through a full retirement wave (at a retirement mark or a child
-   * exit), 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.
+   * exit), the deferred retirement of the last working child while the pool
+   * already carries its bounded over-cap child (retried after the next drain
+   * frees a cap slot), 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" | "pooled-capacity-retirement-deferred"} event - Event name.
    * @returns {void}
    */
   _logPooledCapacityEvent(event) {