rollbridge 0.1.8 → 0.1.10

package/docs/config.md

@@ -127,6 +127,7 @@ legacyTakeover: {
 | --- | --- | --- | --- |
 | `id` | string | **required** | Unique identifier. Appears in `status`, logs, and `ROLLBRIDGE_*` env vars. |
 | `policy` | `"proxied"` \| `"companion"` \| `"singleton"` \| `"service"` | `"companion"` | Lifecycle policy (see [README → Process Policies](../README.md#process-policies)). Exactly one process must be `proxied`. |
+| `deployStrategy` | `"persistent"` \| `"handoff"` | `"persistent"` | Service deploy behavior. Only valid on `policy: "service"`; see below. |
 | `command` | string | **required** | Shell command to run (templated). |
 | `cwd` | string | the release path | Working directory (templated). |
 | `env` | object of string → string | `{}` | Extra environment variables (values templated). Merged over the injected `ROLLBRIDGE_*` vars. |
@@ -135,7 +136,7 @@ legacyTakeover: {
 | `stopSignal` | signal name (e.g. `"SIGTERM"`, `"SIGINT"`, `"SIGQUIT"`) | `"SIGTERM"` | Signal sent to gracefully stop the process; after `gracefulStopMs` it is `SIGKILL`ed. Use a worker's quit signal so it finishes in-flight work before exiting. |
 | `nonBlockingDrain` | boolean | `false` | When a release is retired, drain this process **immediately** (in parallel with the proxied connection drain) instead of after it. Companion processes only — typically background workers (see below). |
 | `lifecycle` | object | no hooks | Command hooks run when gracefully stopping the process (see below). |
-| `gracefulStopMs` | number | `proxy.forceStopTimeoutMs` | Graceful-stop window: time between `stopSignal`/`stopCommand` and `SIGKILL` for this process. |
+| `gracefulStopMs` | number or `"indefinite"` | `proxy.forceStopTimeoutMs` | Graceful-stop window: time between `stopSignal`/`stopCommand` and `SIGKILL` for this process. Use `"indefinite"` to wait for process exit without sending `SIGKILL`. |
 | `restartDelayMs` | number | `1000` | Base delay before restarting this process after a crash (the backoff base; see `restart`). |
 | `restart` | object | unlimited restarts, constant delay | Automatic-restart policy: cap, rolling window, and backoff (see below). |
 | `memory` | object | unset (no monitoring) | Memory supervision: restart the process when its RSS exceeds a limit (see below). |
@@ -161,6 +162,32 @@ restart every replica, or `worker#0` for one). Replicas get `replicaIndex`/
 environment, so each instance can pick a distinct shard, queue, or lock. A single
 process (`replicas: 1`) keeps its plain id and is replica `0` of `1`.
 
+### `processes[].deployStrategy`
+
+`deployStrategy` controls how `policy: "service"` processes behave across deploys:
+
+| Value | Behavior |
+| --- | --- |
+| `"persistent"` | The default. Rollbridge runs one daemon-wide service instance on a stable port. Deploys update the stored template for future restarts but do not replace a healthy service. |
+| `"handoff"` | Rollbridge starts a new release-scoped service instance before the new release's companions and proxied process start. The old release keeps its old service port while it drains, then that old service stops with the old release. |
+
+Use `"handoff"` when release-scoped processes must talk to a same-release service
+while old and new releases overlap. A handoff service must define a **multi-port
+range** so old and new instances can run at the same time:
+
+```js
+{
+  id: "background-jobs-main",
+  policy: "service",
+  deployStrategy: "handoff",
+  command: "npx velocious background-jobs-main",
+  port: {from: 7331, to: 7399}
+}
+```
+
+Reference it from same-release processes with `{{ports.background-jobs-main}}`.
+During a deploy, old workers keep the old port and new workers get the new port.
+
 ### `processes[].lifecycle`
 
 Command hooks run when Rollbridge **gracefully stops** the process — during a
@@ -181,12 +208,13 @@ ignored. Use one or the other.
 
 The full stop sequence is: run `quietCommand` → drain (`drainCommand`, or wait
 `drainTimeoutMs` for the process to exit) → if still running, run `stopCommand`
-or send `stopSignal` → `SIGKILL` after `gracefulStopMs`. Each hook command is run
-through a shell with the process's environment plus `ROLLBRIDGE_PID` (the
-process-group leader's pid, so a hook can `kill -TSTP -$ROLLBRIDGE_PID`). Every
-hook is **bounded by a timeout** (its drain timeout, or `gracefulStopMs`) and its
-failure is non-fatal — the sequence proceeds and `SIGKILL` is always the final
-fallback, so a slow or broken hook can't wedge a stop.
+or send `stopSignal` → `SIGKILL` after `gracefulStopMs` unless
+`gracefulStopMs: "indefinite"` is set. Each hook command is run through a shell
+with the process's environment plus `ROLLBRIDGE_PID` (the process-group leader's
+pid, so a hook can `kill -TSTP -$ROLLBRIDGE_PID`). Every hook is **bounded by a
+timeout** (its drain timeout, `gracefulStopMs`, or 30 seconds when the graceful
+stop window is indefinite) and its failure is non-fatal — the sequence proceeds
+to the stop signal/command so a slow or broken hook can't wedge a stop.
 
 ```js
 {id: "worker", policy: "companion", command: "…", lifecycle: {quietCommand: "kill -TSTP -$ROLLBRIDGE_PID", drainTimeoutMs: 60000}}

package/docs/velocious.md

@@ -14,7 +14,7 @@ A production version of this config lives at
 | Velocious process | Policy | Why |
 | --- | --- | --- |
 | `beacon` | `service` | A shared broker the other processes connect to. It should survive deploys and keep a **stable port**, so workers and the web process always reach the same Beacon. |
-| `background-jobs-main` | `service` (or `singleton`) | The job coordinator. Run it as a `service` when it should outlive releases on a stable port; run it as a `singleton` when it must run the latest release's code after every deploy (see [Choosing the jobs-main policy](#choosing-the-jobs-main-policy)). |
+| `background-jobs-main` | `service` with `deployStrategy: "handoff"` | The job coordinator. Run it as a handoff service so each release's workers and web process use a same-release coordinator while old releases drain (see [Choosing the jobs-main policy](#choosing-the-jobs-main-policy)). |
 | `background-jobs-worker` | `companion` | Release-scoped: one set of workers per active release, started before the web process and running that release's code. |
 | `web` | `proxied` | Receives external HTTP/WebSocket traffic, is health-checked before traffic switches, and is drained on the next deploy. Exactly one process is `proxied`. |
 
@@ -49,10 +49,11 @@ export default {
       port: 7330
     },
 
-    // Job coordinator — waits for Beacon, stable port other jobs processes use.
+    // Job coordinator — one release-scoped service instance per deploy.
     {
       id: "background-jobs-main",
       policy: "service",
+      deployStrategy: "handoff",
       cwd: "{{releasePath}}/backend",
       env: {
         NODE_ENV: "production",
@@ -60,7 +61,7 @@ export default {
         VELOCIOUS_BACKGROUND_JOBS_PORT: "{{port}}"
       },
       command: "wait-for-it 127.0.0.1:{{ports.beacon}} --strict -- npx velocious background-jobs-main",
-      port: 7331
+      port: {from: 7331, to: 7399}
     },
 
     // Workers — one set per release; raise gracefulStopMs to let in-flight
@@ -75,7 +76,7 @@ export default {
         VELOCIOUS_BACKGROUND_JOBS_PORT: "{{ports.background-jobs-main}}"
       },
       command: "wait-for-it 127.0.0.1:{{ports.beacon}} --strict -- wait-for-it 127.0.0.1:{{ports.background-jobs-main}} --strict -- npx velocious background-jobs-worker",
-      gracefulStopMs: 60000
+      gracefulStopMs: "indefinite"
     },
 
     // Web/API — the one proxied process.
@@ -98,11 +99,13 @@ export default {
 
 ## Wiring processes together
 
-Beacon and `background-jobs-main` get **fixed** ports (`7330`, `7331`) because
-they are `service`s — a stable port lets every release's workers and web process
-find them. The proxied `web` process gets a **range** (`{from: 14500, to:
-14599}`); Rollbridge allocates a free port per release so the old and new web
-releases can run side by side during the drain.
+Beacon gets a **fixed** port (`7330`) because it is a persistent `service` — a
+stable port lets every release's processes find the shared broker.
+`background-jobs-main` gets a **range** (`{from: 7331, to: 7399}`) because it is a
+handoff service: Rollbridge allocates a new port per release so old workers keep
+talking to the old coordinator while new workers and web use the new one. The
+proxied `web` process also gets a **range** (`{from: 14500, to: 14599}`) so old
+and new web releases can run side by side during the drain.
 
 Cross-reference ports with `{{ports.<id>}}` and pass them to Velocious through
 `env`. Rollbridge also injects `ROLLBRIDGE_<ID>_PORT` for every process (e.g.
@@ -115,8 +118,8 @@ environment instead of templating if you prefer — see
 Only the `proxied` process is health-checked, so dependent processes must wait
 for their dependencies themselves. Two mechanisms combine:
 
-1. **Policy ordering.** On each deploy Rollbridge starts `service`s first, then
-   the release's `companion`s, then the `proxied` process (see
+1. **Policy ordering.** On each deploy Rollbridge starts handoff `service`s
+   first, then the release's `companion`s, then the `proxied` process (see
    [README → Deploy ordering](../README.md#deploy-ordering)).
 2. **Readiness gating.** `wait-for-it 127.0.0.1:{{ports.beacon}} --strict -- …`
    blocks the command until Beacon's port accepts connections, so
@@ -159,8 +162,9 @@ The worker is a `companion`, so each release runs its own workers:
   is drained and retired — the worker's `stopSignal`, then `SIGKILL` after
   `gracefulStopMs`.
 - Set `stopSignal` to the signal your worker drains on and `gracefulStopMs` to at
-  least your longest in-flight job, so a job gets time to finish before the
-  forced kill. Set `replicas` to run a pool of workers.
+  least your longest in-flight job. Use `gracefulStopMs: "indefinite"` when the
+  worker can safely drain until it exits on its own. Set `replicas` to run a pool
+  of workers.
 
 See [`docs/workers.md`](workers.md) for the full safe background-job deployment
 pattern (companion + `replicas` + `stopSignal`/`lifecycle` hooks +
@@ -185,7 +189,7 @@ jobs across a deploy:
   },
   command: "wait-for-it 127.0.0.1:{{ports.beacon}} --strict -- wait-for-it 127.0.0.1:{{ports.background-jobs-main}} --strict -- npx velocious background-jobs-worker",
   replicas: 4,
-  gracefulStopMs: 60000
+  gracefulStopMs: "indefinite"
 }
 ```
 
@@ -193,9 +197,8 @@ jobs across a deploy:
   each with `ROLLBRIDGE_REPLICA_INDEX`/`ROLLBRIDGE_REPLICA_COUNT` if you shard work.
 - On deploy the new release's workers start before traffic switches; the old
   release's workers receive `SIGTERM` (the default `stopSignal`) when the old
-  release is retired, then `SIGKILL` after `gracefulStopMs` — so size
-  `gracefulStopMs` to your longest job. Both releases' workers briefly consume the
-  shared queue, so keep job code backwards-compatible and jobs idempotent.
+  release is retired, then wait to exit. With `gracefulStopMs: "indefinite"`,
+  Rollbridge does not send a `SIGKILL` fallback.
 
 If your worker quiesces on a command or a non-default signal, add a `lifecycle`
 block — Rollbridge runs `quietCommand`, drains for up to `drainTimeoutMs`, then
@@ -208,27 +211,28 @@ lifecycle: {quietCommand: "kill -TSTP -$ROLLBRIDGE_PID", drainTimeoutMs: 60000}
 
 ### Choosing the jobs-main policy
 
-`background-jobs-main` is duplicate-unsafe (you never want two coordinators), so
-it is either a `service` or a `singleton` — never a `companion`:
+`background-jobs-main` coordinates workers, so choose its lifecycle deliberately:
 
-- **`service`** — keeps running across deploys on its stable port. Workers from
-  every release talk to the same coordinator, so there's no coordination gap on
-  deploy. The trade-off: a `service` keeps running the **release it was started
-  from** and only adopts the latest release's template if it crashes and
-  restarts (or the daemon restarts). If `background-jobs-main` itself needs the
-  newest code immediately after every deploy, this is the wrong policy.
-- **`singleton`** — Rollbridge stops the old instance and then starts the new
-  one on each deploy, so it always runs the latest release's code and two copies
-  never overlap. The trade-off: a brief coordination gap while it restarts.
+- **`service` with `deployStrategy: "handoff"`** — starts one coordinator per
+  release on a port from a range. New workers and web get the new release's port;
+  old workers keep the old release's port while they drain. This is the safest
+  default when the coordinator should run the same code version as its workers.
+- **`service` with the default `deployStrategy: "persistent"`** — keeps one
+  daemon-wide coordinator on a stable port. Workers from every release talk to the
+  same coordinator, but it keeps running the release it was started from and only
+  adopts the latest template if it restarts later.
+- **`singleton`** — stops the old instance and then starts the new one on each
+  deploy, so it always runs the latest release's code and two copies never
+  overlap. The trade-off: a brief coordination gap while it restarts.
 
 Beacon is a broker rather than code that changes per release, so `service` is
 almost always right for it.
 
 ## Verifying
 
-After a deploy, `rollbridge status` should show `beacon` and
-`background-jobs-main` as long-lived `service`s with unchanged ports across
-deploys, one `background-jobs-worker` for the active release, and the `web`
+After a deploy, `rollbridge status` should show `beacon` as a long-lived service
+with an unchanged port, `background-jobs-main` as the active release's handoff
+service, one `background-jobs-worker` for the active release, and the `web`
 process `proxied` with its connection counts. Use
 [`rollbridge logs --process <id>`](cli.md) to read recent output from any
 process, and [`docs/troubleshooting.md`](troubleshooting.md) for health-check,

package/docs/workers.md

@@ -47,7 +47,8 @@ the worker's chance to finish its current job and exit cleanly.
   finish the current job and exit on `SIGTERM` (the default); some use `SIGINT`
   or `SIGQUIT`. Use the one your worker treats as "drain and exit".
 - Set `gracefulStopMs` to at least your longest job's duration, so a job in
-  progress is not cut off by the `SIGKILL` fallback.
+  progress is not cut off by the `SIGKILL` fallback. Use `"indefinite"` only for
+  workers that are safe to leave draining until they exit on their own.
 
 ```js
 {
@@ -56,7 +57,7 @@ the worker's chance to finish its current job and exit cleanly.
   command: "npx velocious background-jobs-worker",
   replicas: 4,
   stopSignal: "SIGTERM",
-  gracefulStopMs: 60000
+  gracefulStopMs: "indefinite"
 }
 ```
 
@@ -73,8 +74,9 @@ the worker's chance to finish its current job and exit cleanly.
 
 Because old workers are retired on the release's **connection** drain (not on
 their own job queue draining), a job still running when the release is retired
-gets only the `gracefulStopMs` window to finish. Keep jobs **idempotent and
-safe to retry** so a job interrupted at the `SIGKILL` fallback can run again.
+gets only the `gracefulStopMs` window to finish, unless `gracefulStopMs` is
+`"indefinite"`. Keep jobs **idempotent and safe to retry** so a job interrupted
+at a finite `SIGKILL` fallback can run again.
 
 ## Command-based lifecycle hooks
 
@@ -107,7 +109,7 @@ in parallel with the connection drain. The new release's workers handle new work
 while the old workers finish their in-flight jobs:
 
 ```js
-{id: "worker", policy: "companion", command: "…", nonBlockingDrain: true, gracefulStopMs: 60000}
+{id: "worker", policy: "companion", command: "…", nonBlockingDrain: true, gracefulStopMs: "indefinite"}
 ```
 
 See [`docs/config.md`](config.md) for `stopSignal`, `replicas`, and

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rollbridge",
-  "version": "0.1.8",
+  "version": "0.1.10",
   "description": "Zero-downtime process supervisor and local traffic switcher for deploy-managed apps.",
   "keywords": [
     "deploy",

package/src/config.js

@@ -13,7 +13,9 @@ import {pathToFileURL} from "node:url"
  * @typedef {{backoffFactor: number, maxDelayMs: number, maxRestarts: number | undefined, windowMs: number}} RestartConfig
  * @typedef {{checkIntervalMs: number, limitBytes: number, warnBytes: number}} MemoryConfig
  * @typedef {{drainCommand?: string, drainTimeoutMs: number, quietCommand?: string, stopCommand?: string}} LifecycleConfig
- * @typedef {{cwd?: string, env: Record<string, string>, gracefulStopMs: number, health?: HealthConfig, id: string, lifecycle: LifecycleConfig, memory?: MemoryConfig, nonBlockingDrain: boolean, outputLines: number, policy: ProcessPolicy, port?: PortRange, replicas: number, restart: RestartConfig, restartDelayMs: number, stopSignal: string, command: string}} ProcessConfig
+ * @typedef {number | "indefinite"} StopTimeoutMs
+ * @typedef {"persistent" | "handoff"} ServiceDeployStrategy
+ * @typedef {{cwd?: string, deployStrategy: ServiceDeployStrategy, env: Record<string, string>, gracefulStopMs: StopTimeoutMs, health?: HealthConfig, id: string, lifecycle: LifecycleConfig, memory?: MemoryConfig, nonBlockingDrain: boolean, outputLines: number, policy: ProcessPolicy, port?: PortRange, replicas: number, restart: RestartConfig, restartDelayMs: number, stopSignal: string, command: string}} ProcessConfig
  * @typedef {{group?: number | string, mode?: number, owner?: number | string, path: string}} ControlConfig
  * @typedef {{drainTimeoutMs: number, forceStopTimeoutMs: number, healthPath: string, healthTimeoutMs: number, host: string, port: number, upstreamHost: string}} ProxyConfig
  * @typedef {{includes: string[], name: string}} LegacyTakeoverProcessConfig
@@ -185,7 +187,7 @@ function normalizeProcess(value, index, proxy, issues) {
   if (!isPlainObject(value)) {
     issues.push({fix: `Define processes[${index}] as a mapping with id, policy, and command.`, message: `processes[${index}] must be an object`})
 
-    return {command: "", cwd: undefined, env: {}, gracefulStopMs: proxy.forceStopTimeoutMs, health: undefined, id: "", lifecycle: {drainTimeoutMs: 0}, memory: undefined, nonBlockingDrain: false, outputLines: 50, policy: "companion", port: undefined, replicas: 1, restart: defaultRestartConfig(), restartDelayMs: 1000, stopSignal: "SIGTERM"}
+    return {command: "", cwd: undefined, deployStrategy: "persistent", env: {}, gracefulStopMs: proxy.forceStopTimeoutMs, health: undefined, id: "", lifecycle: {drainTimeoutMs: 0}, memory: undefined, nonBlockingDrain: false, outputLines: 50, policy: "companion", port: undefined, replicas: 1, restart: defaultRestartConfig(), restartDelayMs: 1000, stopSignal: "SIGTERM"}
   }
 
   const source = value
@@ -193,8 +195,9 @@ function normalizeProcess(value, index, proxy, issues) {
   return {
     command: normalizeString(source.command, `processes[${index}].command`, issues),
     cwd: source.cwd === undefined ? undefined : normalizeString(source.cwd, `processes[${index}].cwd`, issues),
+    deployStrategy: normalizeDeployStrategy(source.deployStrategy, `processes[${index}].deployStrategy`, issues),
     env: normalizeEnv(source.env, `processes[${index}].env`, issues),
-    gracefulStopMs: normalizeNumber(source.gracefulStopMs, `processes[${index}].gracefulStopMs`, issues, {default: proxy.forceStopTimeoutMs}),
+    gracefulStopMs: normalizeStopTimeout(source.gracefulStopMs, `processes[${index}].gracefulStopMs`, proxy.forceStopTimeoutMs, issues),
     health: normalizeHealth(source.health, `processes[${index}].health`, proxy, issues),
     id: normalizeString(source.id, `processes[${index}].id`, issues),
     lifecycle: normalizeLifecycle(source.lifecycle, `processes[${index}].lifecycle`, issues),
@@ -457,6 +460,36 @@ function normalizeStopSignal(value, key, issues) {
   return "SIGTERM"
 }
 
+/**
+ * @param {JsonValue} value - Raw graceful stop timeout.
+ * @param {string} key - Config key.
+ * @param {number} fallback - Default timeout in milliseconds.
+ * @param {ConfigIssue[]} issues - Issue collector.
+ * @returns {StopTimeoutMs} Normalized stop timeout.
+ */
+function normalizeStopTimeout(value, key, fallback, issues) {
+  if (value === "indefinite") return "indefinite"
+
+  const timeoutMs = normalizeNumber(value, key, issues, {default: fallback})
+
+  return nonNegativeOrDefault(timeoutMs, key, issues, fallback, false)
+}
+
+/**
+ * @param {JsonValue} value - Raw service deploy strategy.
+ * @param {string} key - Config key.
+ * @param {ConfigIssue[]} issues - Issue collector.
+ * @returns {ServiceDeployStrategy} Normalized service deploy strategy.
+ */
+function normalizeDeployStrategy(value, key, issues) {
+  if (value === undefined || value === null) return "persistent"
+  if (value === "persistent" || value === "handoff") return value
+
+  issues.push({fix: `Set ${key} to "persistent" or "handoff".`, message: `${key} must be one of: persistent, handoff`})
+
+  return "persistent"
+}
+
 /**
  * @param {JsonValue} value - Raw output retention value.
  * @param {string} key - Config key.
@@ -615,6 +648,16 @@ function validateProcessSet(processes, issues) {
       issues.push({fix: `Set nonBlockingDrain only on a companion process; "${processConfig.id}" is ${processConfig.policy}.`, message: `Process "${processConfig.id}" can only set nonBlockingDrain on a companion process`})
     }
 
+    if (processConfig.deployStrategy === "handoff") {
+      if (processConfig.policy !== "service") {
+        issues.push({fix: `Set deployStrategy: "handoff" only on service processes; "${processConfig.id}" is ${processConfig.policy}.`, message: `Process "${processConfig.id}" can only set deployStrategy: "handoff" on a service process`})
+      } else if (!processConfig.port) {
+        issues.push({fix: `Add a port range to hand off service "${processConfig.id}" so old and new instances can overlap.`, message: `Handoff service "${processConfig.id}" must define a port range`})
+      } else if (processConfig.port.from === processConfig.port.to) {
+        issues.push({fix: `Set service "${processConfig.id}" to a multi-port range, e.g. port: {from: ${processConfig.port.from}, to: ${processConfig.port.from + 99}}.`, message: `Handoff service "${processConfig.id}" must use a multi-port range`})
+      }
+    }
+
     if (processConfig.lifecycle.stopCommand && processConfig.stopSignal !== "SIGTERM") {
       issues.push({fix: `Drop the custom stopSignal "${processConfig.stopSignal}" or lifecycle.stopCommand from "${processConfig.id}": with a stopCommand set, Rollbridge runs it to stop the process instead of sending stopSignal, so the signal is never used.`, message: `Process "${processConfig.id}" sets both lifecycle.stopCommand and a custom stopSignal, but stopCommand replaces stopSignal`})
     }

package/src/daemon.js

@@ -419,7 +419,7 @@ export default class RollbridgeDaemon {
     await release.allocatePorts()
 
     for (const processConfig of this.config.processes) {
-      if (processConfig.policy !== "service") continue
+      if (processConfig.policy !== "service" || processConfig.deployStrategy === "handoff") continue
       if (this.services.has(processConfig.id)) continue
 
       const service = release.buildProcess(processConfig, {shouldRestart: () => !this.stopping})

package/src/managed-process.js

@@ -10,7 +10,8 @@ import {processGroupMembers} from "./process-memory.js"
  * @typedef {"deploy" | "crash" | "manual" | "memory"} ManagedProcessStartReason
  * @typedef {import("node:child_process").ChildProcess["signalCode"]} ProcessExitSignal
  * @typedef {{at: string, line: string, stream: "stdout" | "stderr"}} ManagedProcessLog
- * @typedef {{command: string, cwd: string | undefined, env: Record<string, string | undefined>, lifecycle: import("./config.js").LifecycleConfig, logger: (message: string, data?: Record<string, import("./json.js").JsonValue>) => void, memory: import("./config.js").MemoryConfig | undefined, outputLines: number, restart: import("./config.js").RestartConfig, restartDelayMs: number, shouldRestart: () => boolean, stopSignal: string, stopTimeoutMs: number}} ManagedProcessDefinition
+ * @typedef {import("./config.js").StopTimeoutMs} StopTimeoutMs
+ * @typedef {{command: string, cwd: string | undefined, env: Record<string, string | undefined>, lifecycle: import("./config.js").LifecycleConfig, logger: (message: string, data?: Record<string, import("./json.js").JsonValue>) => void, memory: import("./config.js").MemoryConfig | undefined, outputLines: number, restart: import("./config.js").RestartConfig, restartDelayMs: number, shouldRestart: () => boolean, stopSignal: string, stopTimeoutMs: StopTimeoutMs}} ManagedProcessDefinition
  * @typedef {{children: import("./process-memory.js").ProcessGroupMember[], command: string, cwd: string | undefined, exitCode: number | null | undefined, exitSignal: ProcessExitSignal | undefined, id: string, lastMemoryRestartAt: string | undefined, lastStartReason: ManagedProcessStartReason | undefined, logs: ManagedProcessLog[], memoryRestarts: number, pid: number | undefined, restarts: number, rssBytes: number | undefined, startedAt: string | undefined, state: ManagedProcessState, uptimeMs: number | undefined}} ManagedProcessStatus
  */
 
@@ -29,7 +30,7 @@ export default class ManagedProcess extends EventEmitter {
    * @param {number} args.restartDelayMs - Restart delay.
    * @param {() => boolean} args.shouldRestart - Restart policy callback.
    * @param {string} [args.stopSignal] - Signal sent to gracefully stop the process (default "SIGTERM").
-   * @param {number} args.stopTimeoutMs - Stop timeout.
+   * @param {StopTimeoutMs} args.stopTimeoutMs - Stop timeout.
    */
   constructor({command, cwd, env, id, lifecycle = {drainTimeoutMs: 0}, logger, memory, outputLines, restart = {backoffFactor: 1, maxDelayMs: 0, maxRestarts: undefined, windowMs: 0}, restartDelayMs, shouldRestart, stopSignal = "SIGTERM", stopTimeoutMs}) {
     super()
@@ -356,8 +357,10 @@ export default class ManagedProcess extends EventEmitter {
 
     const {drainCommand, drainTimeoutMs, quietCommand, stopCommand} = this.lifecycle
 
+    const hookTimeoutMs = this.hookTimeoutMs()
+
     // 1. Quiesce: tell the process to stop accepting new work.
-    if (quietCommand) await this.runHook(quietCommand, this.stopTimeoutMs, "quiet command")
+    if (quietCommand) await this.runHook(quietCommand, hookTimeoutMs, "quiet command")
 
     // 2. Drain: let in-flight work finish, bounded by drainTimeoutMs (0 skips the step). A
     //    drainCommand blocks until drained; otherwise wait for the process to exit on its own.
@@ -368,7 +371,7 @@ export default class ManagedProcess extends EventEmitter {
 
     // 3. Stop whatever is still running, then SIGKILL if it outlasts the graceful window.
     if (this.child) {
-      if (stopCommand) await this.runHook(stopCommand, this.stopTimeoutMs, "stop command")
+      if (stopCommand) await this.runHook(stopCommand, hookTimeoutMs, "stop command")
       else this.killProcessGroup(this.stopSignal)
 
       const timeoutMs = options.timeoutMs ?? this.stopTimeoutMs
@@ -383,6 +386,13 @@ export default class ManagedProcess extends EventEmitter {
     this.state = "stopped"
   }
 
+  /** @returns {number} Timeout used for lifecycle hooks. */
+  hookTimeoutMs() {
+    if (this.stopTimeoutMs === "indefinite") return 30000
+
+    return this.stopTimeoutMs
+  }
+
   /**
    * Runs a lifecycle hook command, bounded by a timeout so a hung hook can never block stop().
    * Failures are logged and swallowed — the graceful-stop sequence proceeds (and SIGKILL is the
@@ -465,11 +475,15 @@ export default class ManagedProcess extends EventEmitter {
   }
 
   /**
-   * @param {number} timeoutMs - Timeout.
+   * @param {StopTimeoutMs} timeoutMs - Timeout.
    * @returns {Promise<boolean>} True when the process exited before timeout.
    */
   async waitForExit(timeoutMs) {
     if (!this.exitPromise) return true
+    if (timeoutMs === "indefinite") {
+      await this.exitPromise
+      return true
+    }
 
     let timer = /** @type {ReturnType<typeof setTimeout> | undefined} */ (undefined)
     const timeoutPromise = new Promise((resolve) => {

package/src/release-group.js

@@ -53,6 +53,7 @@ export default class ReleaseGroup extends EventEmitter {
     this.connectionCount = 0
     this.connections = /** @type {ReleaseConnections} */ ({http: 0, websocket: 0})
     this.processes = /** @type {Map<string, ManagedProcess>} */ (new Map())
+    this.handoffServiceIds = /** @type {Set<string>} */ (new Set())
     this.nonBlockingDrainIds = /** @type {Set<string>} */ (new Set())
     this.ports = /** @type {Record<string, number>} */ ({})
     this.servicePorts = servicePorts
@@ -75,6 +76,7 @@ export default class ReleaseGroup extends EventEmitter {
           const processInstance = this.buildProcess(processConfig, {count: processConfig.replicas, index, instanceId})
 
           this.processes.set(instanceId, processInstance)
+          if (processConfig.policy === "service" && processConfig.deployStrategy === "handoff") this.handoffServiceIds.add(instanceId)
           if (processConfig.nonBlockingDrain) this.nonBlockingDrainIds.add(instanceId)
           await processInstance.start("deploy")
         }
@@ -154,11 +156,12 @@ export default class ReleaseGroup extends EventEmitter {
    * @returns {import("./config.js").ProcessConfig[]} Ordered process configs.
    */
   releaseProcessStartOrder() {
-    const releaseProcesses = this.config.processes.filter((processConfig) => !["singleton", "service"].includes(processConfig.policy))
+    const releaseProcesses = this.config.processes.filter((processConfig) => processConfig.policy !== "singleton" && (processConfig.policy !== "service" || processConfig.deployStrategy === "handoff"))
+    const serviceProcesses = releaseProcesses.filter((processConfig) => processConfig.policy === "service")
     const companionProcesses = releaseProcesses.filter((processConfig) => processConfig.policy === "companion")
     const proxiedProcesses = releaseProcesses.filter((processConfig) => processConfig.policy === "proxied")
 
-    return [...companionProcesses, ...proxiedProcesses]
+    return [...serviceProcesses, ...companionProcesses, ...proxiedProcesses]
   }
 
   /** @returns {void} Marks this release active. */
@@ -175,7 +178,7 @@ export default class ReleaseGroup extends EventEmitter {
 
     for (const processConfig of this.config.processes) {
       if (!processConfig.port) continue
-      if (processConfig.policy === "service" && this.servicePorts[processConfig.id] !== undefined) {
+      if (processConfig.policy === "service" && processConfig.deployStrategy !== "handoff" && this.servicePorts[processConfig.id] !== undefined) {
         this.ports[processConfig.id] = this.servicePorts[processConfig.id]
         usedPorts.add(this.servicePorts[processConfig.id])
         continue
@@ -331,7 +334,8 @@ export default class ReleaseGroup extends EventEmitter {
     // connection drain, not held until after it. The rest stop once connections have closed.
     const entries = [...this.processes.entries()]
     const nonBlockingStops = entries.filter(([id]) => this.nonBlockingDrainIds.has(id)).map(([, processInstance]) => processInstance.stop())
-    const connectionDependent = entries.filter(([id]) => !this.nonBlockingDrainIds.has(id)).map(([, processInstance]) => processInstance)
+    const handoffServices = entries.filter(([id]) => this.handoffServiceIds.has(id)).map(([, processInstance]) => processInstance)
+    const connectionDependent = entries.filter(([id]) => !this.nonBlockingDrainIds.has(id) && !this.handoffServiceIds.has(id)).map(([, processInstance]) => processInstance)
 
     if (this.connectionCount > 0) {
       await new Promise((resolve) => {
@@ -345,6 +349,7 @@ export default class ReleaseGroup extends EventEmitter {
 
     await Promise.allSettled(connectionDependent.map((processInstance) => processInstance.stop()))
     await Promise.allSettled(nonBlockingStops)
+    await Promise.allSettled(handoffServices.map((processInstance) => processInstance.stop()))
     this.state = "stopped"
     this.stoppedAt = new Date().toISOString()
   }

package/test/config-validation.test.js

@@ -204,6 +204,81 @@ test("validateConfig defaults lifecycle, accepts hooks, and rejects bad values",
   assert.deepEqual(validateLifecycle({stopCommand: "kill -TERM $ROLLBRIDGE_PID"}).issues, [])
 })
 
+test("validateConfig accepts indefinite graceful stop windows", () => {
+  const {config, issues} = validateConfig({
+    application: "demo",
+    control: {path: "/tmp/demo.sock"},
+    processes: [
+      {command: "run web", id: "web", policy: "proxied", port: {from: 18000, to: 18099}},
+      {command: "run worker", gracefulStopMs: "indefinite", id: "worker", policy: "companion"}
+    ],
+    proxy: {host: "127.0.0.1", port: 8182}
+  })
+
+  assert.deepEqual(issues, [])
+  assert.equal(config.processes[1].gracefulStopMs, "indefinite")
+})
+
+test("validateConfig accepts handoff services only with a multi-port service range", () => {
+  const valid = validateConfig({
+    application: "demo",
+    control: {path: "/tmp/demo.sock"},
+    processes: [
+      {command: "run web", id: "web", policy: "proxied", port: {from: 18000, to: 18099}},
+      {command: "run service", deployStrategy: "handoff", id: "beacon", policy: "service", port: {from: 18100, to: 18199}}
+    ],
+    proxy: {host: "127.0.0.1", port: 8182}
+  })
+
+  assert.deepEqual(valid.issues, [])
+  assert.equal(valid.config.processes[1].deployStrategy, "handoff")
+
+  const defaulted = validateConfig({
+    application: "demo",
+    control: {path: "/tmp/demo.sock"},
+    processes: [{command: "run web", id: "web", policy: "proxied", port: {from: 18000, to: 18099}}],
+    proxy: {host: "127.0.0.1", port: 8182}
+  })
+
+  assert.equal(defaulted.config.processes[0].deployStrategy, "persistent")
+
+  const invalidProcess = validateConfig({
+    application: "demo",
+    control: {path: "/tmp/demo.sock"},
+    processes: [
+      {command: "run web", id: "web", policy: "proxied", port: {from: 18000, to: 18099}},
+      {command: "run worker", deployStrategy: "handoff", id: "worker", policy: "companion"}
+    ],
+    proxy: {host: "127.0.0.1", port: 8182}
+  })
+
+  assert.ok(invalidProcess.issues.some((issue) => issue.message === "Process \"worker\" can only set deployStrategy: \"handoff\" on a service process"), JSON.stringify(invalidProcess.issues))
+
+  const missingPort = validateConfig({
+    application: "demo",
+    control: {path: "/tmp/demo.sock"},
+    processes: [
+      {command: "run web", id: "web", policy: "proxied", port: {from: 18000, to: 18099}},
+      {command: "run service", deployStrategy: "handoff", id: "beacon", policy: "service"}
+    ],
+    proxy: {host: "127.0.0.1", port: 8182}
+  })
+
+  assert.ok(missingPort.issues.some((issue) => issue.message === "Handoff service \"beacon\" must define a port range"), JSON.stringify(missingPort.issues))
+
+  const fixedPort = validateConfig({
+    application: "demo",
+    control: {path: "/tmp/demo.sock"},
+    processes: [
+      {command: "run web", id: "web", policy: "proxied", port: {from: 18000, to: 18099}},
+      {command: "run service", deployStrategy: "handoff", id: "beacon", policy: "service", port: 18100}
+    ],
+    proxy: {host: "127.0.0.1", port: 8182}
+  })
+
+  assert.ok(fixedPort.issues.some((issue) => issue.message === "Handoff service \"beacon\" must use a multi-port range"), JSON.stringify(fixedPort.issues))
+})
+
 test("validateConfig rejects a custom stopSignal alongside a stopCommand that would ignore it", () => {
   /**
    * @param {Record<string, import("../src/json.js").JsonValue>} overrides - Extra fields merged onto the worker process.

package/test/fixtures/dependent-app.js

@@ -1,10 +1,12 @@
 // @ts-check
 
 import http from "node:http"
+import crypto from "node:crypto"
 
 const port = Number(requiredEnv("ROLLBRIDGE_PORT"))
 const servicePort = Number(requiredEnv("ROLLBRIDGE_BEACON_PORT"))
 const releaseId = process.env.ROLLBRIDGE_RELEASE_ID || "unknown"
+const sockets = new Set()
 
 await waitForService()
 
@@ -21,6 +23,37 @@ const server = http.createServer((request, response) => {
 
 process.on("SIGTERM", () => {
   server.close(() => process.exit(0))
+
+  if (sockets.size === 0) {
+    setTimeout(() => process.exit(0), 10)
+  }
+})
+
+server.on("upgrade", (request, socket) => {
+  const key = request.headers["sec-websocket-key"]
+
+  if (typeof key !== "string") {
+    socket.end("HTTP/1.1 400 Bad Request\r\n\r\n")
+    return
+  }
+
+  const accept = crypto
+    .createHash("sha1")
+    .update(`${key}258EAFA5-E914-47DA-95CA-C5AB0DC85B11`)
+    .digest("base64")
+
+  sockets.add(socket)
+  socket.once("close", () => sockets.delete(socket))
+  socket.on("data", () => {
+    socket.end()
+  })
+  socket.write([
+    "HTTP/1.1 101 Switching Protocols",
+    "Upgrade: websocket",
+    "Connection: Upgrade",
+    `Sec-WebSocket-Accept: ${accept}`,
+    "\r\n"
+  ].join("\r\n"))
 })
 
 server.listen(port, "127.0.0.1")

package/test/managed-process.test.js

@@ -381,6 +381,39 @@ test("sends the configured stopSignal as the graceful stop signal", async () =>
   assert.equal(managed.status().state, "stopped")
 })
 
+test("indefinite stop waits for the process to exit without SIGKILL", async () => {
+  const managed = new ManagedProcess({
+    command: `${JSON.stringify(process.execPath)} -e ${JSON.stringify("process.on('SIGTERM', () => setTimeout(() => process.exit(0), 150)); setInterval(() => {}, 1000)")}`,
+    cwd: undefined,
+    env: {},
+    id: "worker",
+    logger: () => {},
+    outputLines: 50,
+    restartDelayMs: 10,
+    shouldRestart: () => false,
+    stopSignal: "SIGTERM",
+    stopTimeoutMs: "indefinite"
+  })
+  /** @type {string[]} */
+  const signals = []
+  const killProcessGroup = managed.killProcessGroup.bind(managed)
+
+  managed.killProcessGroup = (signal) => {
+    signals.push(signal)
+    killProcessGroup(signal)
+  }
+
+  try {
+    await managed.start()
+    await managed.stop()
+
+    assert.equal(managed.status().state, "stopped")
+    assert.deepEqual(signals, ["SIGTERM"])
+  } finally {
+    await managed.stop()
+  }
+})
+
 test("a memory restart respawns and is counted when the supervisor still wants the process", async () => {
   const managed = buildLongLived(() => true)
 

package/test/rollbridge.test.js

@@ -243,6 +243,80 @@ test("service processes start before releases and restart with the latest deploy
   }
 })
 
+test("handoff services start per release and drain with their release", async () => {
+  const fixture = await createFixture({handoffService: true, webDependsOnService: true})
+  const daemon = await startDaemon(fixture.config)
+  /** @type {WebSocket | undefined} */
+  let socket
+
+  try {
+    await daemon.deploy({releaseId: "v1", releasePath: fixture.root, revision: "v1"})
+    socket = await openWebSocket(daemon)
+    const v1 = statusRelease(daemon, "v1")
+    const v1Service = v1.processes.find((processStatus) => processStatus.id === "beacon")
+
+    assert.ok(v1Service?.pid, "v1 service should be running")
+    assert.equal(v1.ports.beacon > 0, true)
+
+    await daemon.deploy({releaseId: "v2", releasePath: fixture.root, revision: "v2"})
+    const v2 = statusRelease(daemon, "v2")
+    const v2Service = v2.processes.find((processStatus) => processStatus.id === "beacon")
+
+    assert.ok(v2Service?.pid, "v2 service should be running")
+    assert.notEqual(v2.ports.beacon, v1.ports.beacon)
+    assert.equal(statusRelease(daemon, "v1").processes.find((processStatus) => processStatus.id === "beacon")?.state, "running")
+
+    socket.close()
+    socket = undefined
+
+    await waitFor(() => statusRelease(daemon, "v1").state === "stopped")
+    assert.equal(statusRelease(daemon, "v1").processes.find((processStatus) => processStatus.id === "beacon")?.state, "stopped")
+
+    const events = await processEvents(fixture.serviceLogPath)
+
+    assert.ok(events.some((event) => event.event === "start" && event.releaseId === "v1"), "v1 service should start")
+    assert.ok(events.some((event) => event.event === "start" && event.releaseId === "v2"), "v2 service should start")
+    assert.ok(events.some((event) => event.event === "stop" && event.releaseId === "v1"), "v1 service should stop after drain")
+  } finally {
+    if (socket) socket.close()
+    await daemon.shutdown()
+    await fs.rm(fixture.root, {force: true, recursive: true})
+  }
+})
+
+test("handoff services stop after release-local dependents finish draining", async () => {
+  const fixture = await createFixture({handoffService: true, nonBlockingDrainWorker: true, webDependsOnService: true, workerStopDelayMs: 200})
+  const daemon = await startDaemon(fixture.config)
+  /** @type {WebSocket | undefined} */
+  let socket
+
+  try {
+    await daemon.deploy({releaseId: "v1", releasePath: fixture.root, revision: "v1"})
+    socket = await openWebSocket(daemon)
+    await daemon.deploy({releaseId: "v2", releasePath: fixture.root, revision: "v2"})
+
+    await waitFor(() => statusRelease(daemon, "v1").processes.find((processStatus) => processStatus.id === "worker")?.state === "stopped")
+
+    const drainingRelease = statusRelease(daemon, "v1")
+
+    assert.equal(drainingRelease.state, "draining")
+    assert.equal(drainingRelease.processes.find((processStatus) => processStatus.id === "beacon")?.state, "running")
+
+    socket.close()
+    socket = undefined
+    await waitFor(() => statusRelease(daemon, "v1").state === "stopped")
+
+    const events = await processEvents(fixture.serviceLogPath)
+    const v1ServiceStop = events.find((event) => event.event === "stop" && event.releaseId === "v1")
+
+    assert.ok(v1ServiceStop, "v1 handoff service should stop after release drain")
+  } finally {
+    if (socket) socket.close()
+    await daemon.shutdown()
+    await fs.rm(fixture.root, {force: true, recursive: true})
+  }
+})
+
 test("a replicated companion starts one instance per replica, and restart targets one or all", async () => {
   const fixture = await createFixture({companionReplicas: 3})
   const daemon = await startDaemon(fixture.config)
@@ -972,7 +1046,7 @@ test("deploy can ensure the daemon before sending the release command", async ()
 })
 
 /**
- * @param {{companionReplicas?: number, includeCompanion?: boolean, includeService?: boolean, includeSingleton?: boolean, memoryLimitBytes?: number, nonBlockingDrainWorker?: boolean, persistState?: boolean, proxyHost?: string, singletonCwd?: string, webCommand?: string, webDependsOnService?: boolean, webHealthTimeoutMs?: number}} [options] - Fixture options.
+ * @param {{companionReplicas?: number, handoffService?: boolean, includeCompanion?: boolean, includeService?: boolean, includeSingleton?: boolean, memoryLimitBytes?: number, nonBlockingDrainWorker?: boolean, persistState?: boolean, proxyHost?: string, singletonCwd?: string, webCommand?: string, webDependsOnService?: boolean, webHealthTimeoutMs?: number, workerStopDelayMs?: number}} [options] - Fixture options.
  * @returns {Promise<{config: import("../src/config.js").RollbridgeConfig, root: string, serviceLogPath: string, singletonLogPath: string, statePath: string}>} Fixture data.
  */
 async function createFixture(options = {}) {
@@ -983,15 +1057,16 @@ async function createFixture(options = {}) {
   /** @type {Array<Record<string, import("../src/json.js").JsonValue>>} */
   const processes = []
 
-  if (options.includeService) {
+  if (options.includeService || options.handoffService) {
     processes.push({
       command: `${JSON.stringify(process.execPath)} ${JSON.stringify(serviceAppPath)} --release={{releaseId}}`,
+      ...(options.handoffService ? {deployStrategy: "handoff"} : {}),
       env: {
         ROLLBRIDGE_SERVICE_LOG: serviceLogPath
       },
       id: "beacon",
       policy: "service",
-      port: {from: 0, to: 0},
+      port: options.handoffService ? {from: 15000, to: 15099} : {from: 0, to: 0},
       restartDelayMs: 50
     })
   }
@@ -1015,7 +1090,7 @@ async function createFixture(options = {}) {
 
   if (options.nonBlockingDrainWorker) {
     processes.push({
-      command: `${JSON.stringify(process.execPath)} -e ${JSON.stringify("setInterval(() => {}, 1000)")}`,
+      command: `${JSON.stringify(process.execPath)} -e ${JSON.stringify(`process.on('SIGTERM', () => setTimeout(() => process.exit(0), ${options.workerStopDelayMs || 0})); setInterval(() => {}, 1000)`)}`,
       id: "worker",
       nonBlockingDrain: true,
       policy: "companion"