rollbridge 0.1.30 → 0.1.32

package/AGENTS.md

@@ -9,8 +9,10 @@ process lifecycle, retained generations, ports, and recovery state.
 
 - One runtime generation is one release-scoped `background-jobs-main` plus its
   worker pool. Start the complete candidate generation before activation.
-- After activation, retire the old generation as one unit. Its main stops
-  schedules, new dispatch, and new ordinary worker handoffs; its workers stop
+- For an explicit candidate lifecycle, retire the old generation as one unit,
+  wait for its acknowledgement, then activate the candidate and commit traffic
+  synchronously. The old main stops schedules, new dispatch, and new ordinary
+  worker handoffs; its workers stop
   accepting handoffs. The old main remains running with those workers and owns
   their connections, lease fencing, report acceptance and acknowledgement, and
   durable store transitions. The worker/reporting side durably retries terminal
@@ -40,10 +42,13 @@ implemented. Do not claim production compliance when source/config still uses a
 fixed jobs-main, worker adoption by a new main, destructive orphan recovery, or
 synchronous cleanup.
 
-Current same-authority behavior quiesces configured handoff services after
-candidate activation, retains concurrent generations, reports live release
-references, and can opt into `ownerRecovery` so a durable process guardian
-preserves and reconstructs active/draining generations after daemon process
+Current same-authority behavior preserves activate-then-retire ordering when no
+activation hook is configured. An opt-in handoff-service `activateCommand`
+durably journals old-retire/new-activate ordering, retains concurrent generations,
+reports live release references, journals post-commit singleton completion, and
+restores an active coordinator's generation-scoped role after process restart.
+It requires `ownerRecovery` so a durable guardian preserves exact per-release
+definitions and reconstructs active/draining generations after daemon process
 exit. With `ownerRecovery` and the same `statePath` transaction anchor,
 `ensure-daemon` also replaces incompatible config, control-socket, package, and
 runtime owners through a guardian-fenced candidate-first handoff while retaining

package/README.md

@@ -49,6 +49,9 @@ export default {
     path: "/tmp/rollbridge-ticket-server.sock"
   },
 
+  statePath: "/var/lib/rollbridge/ticket-server.state.json",
+  ownerRecovery: {reconnectGraceMs: 30000},
+
   proxy: {
     host: "127.0.0.1",
     port: 8182,
@@ -82,8 +85,12 @@ export default {
       policy: "service",
       deployStrategy: "handoff",
       cwd: "{{releasePath}}",
+      env: {VELOCIOUS_BACKGROUND_JOBS_LIFECYCLE_SOCKET: "{{releasePath}}/tmp/background-jobs-main.sock"},
       command: "env VELOCIOUS_BACKGROUND_JOBS_PORT={{port}} npx velocious background-jobs-main",
-      lifecycle: {quietCommand: "appctl jobs-main-retire --pid $ROLLBRIDGE_PID"},
+      lifecycle: {
+        activateCommand: 'npx velocious background-jobs:activate --generation "$ROLLBRIDGE_RELEASE_ID" --socket "$VELOCIOUS_BACKGROUND_JOBS_LIFECYCLE_SOCKET"',
+        quietCommand: 'npx velocious background-jobs:retire --generation "$ROLLBRIDGE_RELEASE_ID" --socket "$VELOCIOUS_BACKGROUND_JOBS_LIFECYCLE_SOCKET"'
+      },
       port: {from: 7331, to: 7399}
     },
     {
@@ -98,8 +105,8 @@ export default {
 }
 ```
 
-`appctl jobs-main-retire` is illustrative; replace it with a reviewed command
-that quiesces the real jobs-main without exiting it.
+The lifecycle socket path is illustrative; set it to the reviewed release-local
+Velocious socket used by jobs-main.
 
 Each process retains its most recent stdout/stderr lines and reports them in
 `status`. Set `outputLines` (a positive integer, default 50) per process to keep
@@ -173,12 +180,16 @@ handoffs as soon as its release retires, independently of the proxied connection
 drain. Its release-scoped handoff jobs-main remains running to supervise existing
 handoffs and exits only after the worker pool has drained.
 
-Give the handoff jobs-main a `lifecycle.quietCommand` that stops schedules,
-dispatch, and new handoffs without terminating the main. After candidate health
-and traffic activation, Rollbridge waits only for this bounded quiescence step,
-then returns while the old main and workers drain together. A failed quiet hook
-is reported as `retirementError`; Rollbridge leaves that generation alive for
-diagnosis instead of silently continuing to stop it.
+For a coordinator that starts quiescent, give the handoff jobs-main paired
+`lifecycle.activateCommand` and `quietCommand` hooks. After candidate health,
+Rollbridge waits for old retirement, waits for candidate activation, and commits
+the active proxy target without an awaited boundary. The durable transition is
+generation-scoped and resumable; failures remain visible and block unrelated
+deploys. Post-commit singleton replacement is also journaled and must complete
+before an exact retry reports success. If the active coordinator restarts,
+Rollbridge restores its active role with the same bounded, generation-scoped
+activation command before reporting it running. Omit `activateCommand` to
+preserve the existing hook-free ordering.
 
 See [`docs/workers.md`](docs/workers.md) for the full release-generation
 deployment pattern: a handoff `background-jobs-main`, its companion worker pool,
@@ -384,7 +395,10 @@ candidate coordinator.
   deployStrategy: "handoff",
   cwd: "{{releasePath}}",
   command: "npx velocious background-jobs-main",
-  lifecycle: {quietCommand: "appctl jobs-main-retire --pid $ROLLBRIDGE_PID"},
+  lifecycle: {
+    activateCommand: 'npx velocious background-jobs:activate --generation "$ROLLBRIDGE_RELEASE_ID" --socket "$VELOCIOUS_BACKGROUND_JOBS_LIFECYCLE_SOCKET"',
+    quietCommand: 'npx velocious background-jobs:retire --generation "$ROLLBRIDGE_RELEASE_ID" --socket "$VELOCIOUS_BACKGROUND_JOBS_LIFECYCLE_SOCKET"'
+  },
   port: {from: 7331, to: 7399}
 }
 ```
@@ -396,8 +410,10 @@ On `rollbridge deploy`, the required ordering is:
 1. starts any missing persistent service and the candidate's handoff services;
 2. starts the new release's `companion`s, then its `proxied` process, and
    health-checks the proxied process;
-3. switches new traffic to the new release;
-4. quiesces the previous jobs-main and worker pool as one retired generation;
+3. when `activateCommand` is configured, retires and acknowledges the previous
+   jobs generation, then activates and acknowledges the candidate;
+4. synchronously switches new traffic to the new release (hook-free configs keep
+   the existing switch-then-retire behavior);
 5. replaces `singleton`s (stops the old one, then starts the new one);
 6. returns success without waiting for the previous generation or its independent
    HTTP/WebSocket drain; Rollbridge supervises all retained drains in the

package/changelog.d/20260830-release-generation-activation-lifecycle.md

@@ -0,0 +1,9 @@
+### Added
+
+- Add an opt-in, durable `lifecycle.activateCommand` for one release-scoped
+  handoff service. Rollbridge now supports strict old-retire acknowledgement,
+  candidate-activate acknowledgement, and synchronous active/proxy commit with
+  exact transition recovery and resume. Exact release definitions remain private
+  to guardian recovery, post-commit singleton work is resumable, unresolved
+  control mutations are fenced, and an active coordinator restores its role after
+  restart. Hook-free configs keep their existing deploy behavior.

package/docs/cli.md

@@ -149,16 +149,19 @@ for old workers, jobs, or HTTP/WebSocket connections to finish. Prints
 If the new release fails to start or health-check, the previous release stays
 active and the command errors.
 
-After activation, deploy waits for bounded quiet hooks of old handoff services
-and `nonBlockingDrain` companions, then returns without waiting for their drains.
-A failure is logged and exposed as `retirementError`; the generation stays alive.
-The successful activation response also includes
-`retirement: {status: "quiescence_failed", releaseId, error}` so callers cannot
-mistake the retirement failure for an unqualified transition.
+With an opt-in handoff-service `lifecycle.activateCommand`, deploy journals the
+exact transition, waits for old retirement acknowledgement, waits for candidate
+activation acknowledgement, and synchronously commits the active proxy target.
+An unresolved failure blocks different deploys; only the exact same release,
+path, revision, and config authority may explicitly resume its incomplete
+idempotent phase. A durable `committed_pending` phase keeps exact retry from
+reporting success until singleton replacement finishes. Stop, restart, and
+rollback mutations are rejected while the transition is unresolved. Hook-free
+configs retain the existing post-activation quiet behavior and retirement result.
 `status.releaseReferences` lists `{releaseId, releasePath}` for every active or
 draining release and excludes fully stopped history.
 
-After candidate activation, `Daemon.deploy()` begins old-generation retirement
+For hook-free configs, after candidate activation `Daemon.deploy()` begins old-generation retirement
 and asynchronous drain before awaiting singleton replacement. A singleton
 replacement failure can therefore return non-zero while the candidate remains
 active, but it cannot leave the old jobs generation dispatching.

package/docs/config.md

@@ -255,13 +255,16 @@ range** so old and new instances can run at the same time:
   policy: "service",
   deployStrategy: "handoff",
   command: "npx velocious background-jobs-main",
-  lifecycle: {quietCommand: "appctl jobs-main-retire --pid $ROLLBRIDGE_PID"},
+  lifecycle: {
+    activateCommand: 'npx velocious background-jobs:activate --generation "$ROLLBRIDGE_RELEASE_ID" --socket "$VELOCIOUS_BACKGROUND_JOBS_LIFECYCLE_SOCKET"',
+    quietCommand: 'npx velocious background-jobs:retire --generation "$ROLLBRIDGE_RELEASE_ID" --socket "$VELOCIOUS_BACKGROUND_JOBS_LIFECYCLE_SOCKET"'
+  },
   port: {from: 7331, to: 7399}
 }
 ```
 
-The `appctl` command is illustrative; the application must provide a reviewed
-equivalent that quiesces admission without terminating jobs-main.
+The lifecycle socket path is illustrative; set it to the reviewed release-local
+Velocious socket used by jobs-main.
 
 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.
@@ -271,14 +274,38 @@ retirement must quiesce the old jobs-main's scheduling, dispatch, and new worker
 handoffs while keeping it with its workers until their accepted work settles.
 Workers are not adopted by the new service.
 
-Configure `lifecycle.quietCommand` on the handoff service to stop schedules,
-dispatch, and new handoffs without exiting. Immediately after activation,
-Rollbridge quiesces it with `nonBlockingDrain` companions, then returns without
-waiting for their drain. A failed hook leaves the generation alive, records
-`retirementError`, and emits `release retirement quiescence failed`. Durable
-same-authority recovery and guardian-fenced incompatible
-config/control-socket/package/runtime replacement are available with
-`ownerRecovery`.
+Configure `lifecycle.activateCommand` and `lifecycle.quietCommand` on one handoff
+service when the service starts as a quiescent candidate and requires an explicit
+generation transition. Rollbridge starts and health-checks the complete candidate,
+waits for the old generation's strict retirement acknowledgement, waits for the
+candidate's strict activation acknowledgement, then commits the active release and
+proxy target synchronously. Activation is always bounded to 30 seconds;
+retirement uses the process's `gracefulStopMs` bound (or 30 seconds when that
+window is `"indefinite"`). Both run with the process environment plus
+`ROLLBRIDGE_PID`.
+
+This opt-in mode requires `statePath` and `ownerRecovery`. Rollbridge journals the
+exact candidate, previous release, config authority, phase, and failure. An
+unresolved transition blocks a different deploy; an explicit deploy with the same
+release id, path, revision, and config may resume only its incomplete idempotent
+phase. Once the health-ready candidate is journaled, its exact config becomes the
+transition authority even if a later hook fails. A recorded failed hook is not
+retried merely because daemon ownership changes. Omit `activateCommand` to retain
+the existing activate-then-retire behavior.
+
+The synchronous traffic assignment is persisted as `committed_pending` before
+Rollbridge awaits singleton replacement. Exact retry or unambiguous owner recovery
+finishes that idempotent post-commit work before the transition becomes
+`committed` and deploy reports success. Stop, restart, and rollback operations are
+rejected while any transition remains unresolved. Exact per-release definitions
+stay in the guardian's authenticated private recovery state; `statePath` remains a
+secret-safe status and transaction anchor.
+
+An activation-owning handoff service also carries a durable desired role. If its
+active process automatically or manually restarts, Rollbridge runs the exact
+generation-scoped `activateCommand` once before marking it running. A failed role
+restoration is surfaced and the process remains failed rather than being treated
+as active. Retired generations remain fenced and are not restarted.
 
 ### `processes[].lifecycle`
 
@@ -294,7 +321,8 @@ legitimate hours-long generation drains are valid.
 
 | Field | Type | Default | Description |
 | --- | --- | --- | --- |
-| `lifecycle.quietCommand` | string | unset | Run first to tell the process to stop accepting new work. |
+| `lifecycle.activateCommand` | string | unset | For one handoff service, acknowledge activation of its already-started candidate generation after the previous generation has acknowledged retirement. Requires `quietCommand`, `statePath`, and `ownerRecovery`; bounded to 30 seconds. |
+| `lifecycle.quietCommand` | string | unset | Run first to tell the process to stop accepting new work. Bounded by `gracefulStopMs`, or 30 seconds when that window is `"indefinite"`. |
 | `lifecycle.drainCommand` | string | unset | Run after quieting to wait until the process has drained (it blocks until done). When unset, Rollbridge instead waits up to `drainTimeoutMs` for the process to exit on its own. Requires a positive `drainTimeoutMs` (which bounds it). |
 | `lifecycle.drainTimeoutMs` | non-negative number | `0` | Bounds the drain step. `0` **skips the drain step entirely** (no `drainCommand`, no wait). |
 | `lifecycle.stopCommand` | string | unset | Run to stop the process instead of sending `stopSignal`, if it is still running after draining. |
@@ -439,6 +467,6 @@ Rollbridge sets these in every managed process's environment (the process's own
 - `restart.maxRestarts` must be a non-negative integer (omit it for unlimited restarts); `restart.backoffFactor` must be a number ≥ 1; `restart.windowMs` and `restart.maxDelayMs` must be non-negative numbers.
 - When `memory` is set, `memory.limitBytes` must be a positive integer, `memory.warnBytes` a non-negative integer, and `memory.checkIntervalMs` a positive number.
 - `replicas` must be a positive integer; `replicas > 1` is allowed only on a `companion` process without a `port`. Process ids must not contain `#` (reserved for replica instance ids).
-- `lifecycle.quietCommand`/`drainCommand`/`stopCommand` must be strings when set, and `lifecycle.drainTimeoutMs` a non-negative number; `lifecycle.drainCommand` requires a positive `lifecycle.drainTimeoutMs`. A `lifecycle.stopCommand` may not be combined with a custom `stopSignal` (the `stopCommand` runs instead of the signal, so the signal would be ignored).
+- `lifecycle.activateCommand`/`quietCommand`/`drainCommand`/`stopCommand` must be strings when set, and `lifecycle.drainTimeoutMs` a non-negative number; `lifecycle.drainCommand` requires a positive `lifecycle.drainTimeoutMs`. `activateCommand` is allowed on at most one handoff service, requires that service's `quietCommand`, and requires `statePath` plus `ownerRecovery`. A `lifecycle.stopCommand` may not be combined with a custom `stopSignal` (the `stopCommand` runs instead of the signal, so the signal would be ignored).
 - `nonBlockingDrain` must be a boolean, and is allowed only on a `companion` process.
 - `statePath` must be a string when set.

package/docs/tensorbuzz-runbook.md

@@ -24,10 +24,12 @@ while a newer generation is active.
 1. Prepare the candidate release and run backwards-compatible migrations.
 2. Start the candidate jobs-main on a new port, then its worker pool and web
    process. Health-check web before activation.
-3. Activate the candidate release and switch new traffic.
-4. Retire the previous jobs-main and workers as one generation. Jobs-main stops
+3. Retire the previous jobs-main and workers as one generation and wait for its
+   exact lifecycle-socket acknowledgement. Jobs-main stops
    schedule ownership, new dispatch, and new handoffs; workers stop accepting
    handoffs.
+4. Activate the candidate with its exact generation and lifecycle socket, then
+   synchronously switch new traffic.
 5. Return deploy success and release the deploy lock. Do not wait for old jobs,
    workers, jobs-main, HTTP/WebSocket connections, or other retained services.
 

package/docs/velocious.md

@@ -54,10 +54,14 @@ export default {
       env: {
         NODE_ENV: "production",
         VELOCIOUS_BEACON_PORT: "{{ports.beacon}}",
-        VELOCIOUS_BACKGROUND_JOBS_PORT: "{{port}}"
+        VELOCIOUS_BACKGROUND_JOBS_PORT: "{{port}}",
+        VELOCIOUS_BACKGROUND_JOBS_LIFECYCLE_SOCKET: "{{releasePath}}/tmp/background-jobs-main.sock"
       },
       command: "wait-for-it 127.0.0.1:{{ports.beacon}} --strict -- npx velocious background-jobs-main",
-      lifecycle: {quietCommand: "appctl jobs-main-retire --pid $ROLLBRIDGE_PID"},
+      lifecycle: {
+        activateCommand: 'npx velocious background-jobs:activate --generation "$ROLLBRIDGE_RELEASE_ID" --socket "$VELOCIOUS_BACKGROUND_JOBS_LIFECYCLE_SOCKET"',
+        quietCommand: 'npx velocious background-jobs:retire --generation "$ROLLBRIDGE_RELEASE_ID" --socket "$VELOCIOUS_BACKGROUND_JOBS_LIFECYCLE_SOCKET"'
+      },
       port: {from: 7331, to: 7399}
     },
     {
@@ -91,8 +95,9 @@ export default {
 }
 ```
 
-`appctl` is a placeholder for a reviewed Velocious/application integration that
-quiesces jobs-main admission without terminating its worker/report endpoint.
+The lifecycle socket path must match the release's reviewed Velocious generation
+configuration. Rollbridge invokes the exact generation-scoped commands without
+polling, PID discovery, or an application-specific wrapper.
 
 Beacon keeps its fixed port because it is intentionally shared. Jobs-main uses a
 range because every release gets its own coordinator. Same-release
@@ -104,9 +109,16 @@ old endpoint while candidate workers use the candidate endpoint.
 Run backwards-compatible migrations before activation, then invoke
 `rollbridge deploy` with the prepared release. Rollbridge starts the candidate
 jobs-main, its complete worker pool, and the web process before health gating and
-activation. A candidate startup or health failure leaves the previous release
-active.
-
+activation. Velocious generation mode starts jobs-main quiescent; the exact
+`background-jobs:activate --generation … --socket …` acknowledgement is what
+makes that generation active. A candidate startup or health failure leaves the
+previous release active.
+
+For the opt-in lifecycle above, Rollbridge first waits for the old generation's
+retirement acknowledgement, then for candidate activation, and commits the active
+proxy target synchronously. On the first deploy there is no retirement step.
+If an active jobs-main process restarts, Rollbridge repeats that same exact,
+idempotent activation command once before reporting the process running.
 After successful activation, the deploy returns without waiting for any retired
 generation or HTTP/WebSocket connection to finish. The old and new release code
 may therefore overlap for hours. Keep schema, queue payloads, and external side

package/docs/workers.md

@@ -17,7 +17,10 @@ fixed port such as `7330`.
   policy: "service",
   deployStrategy: "handoff",
   command: "npx velocious background-jobs-main",
-  lifecycle: {quietCommand: "appctl jobs-main-retire --pid $ROLLBRIDGE_PID"},
+  lifecycle: {
+    activateCommand: 'npx velocious background-jobs:activate --generation "$ROLLBRIDGE_RELEASE_ID" --socket "$VELOCIOUS_BACKGROUND_JOBS_LIFECYCLE_SOCKET"',
+    quietCommand: 'npx velocious background-jobs:retire --generation "$ROLLBRIDGE_RELEASE_ID" --socket "$VELOCIOUS_BACKGROUND_JOBS_LIFECYCLE_SOCKET"'
+  },
   port: {from: 7331, to: 7399}
 },
 {
@@ -31,8 +34,8 @@ fixed port such as `7330`.
 }
 ```
 
-The illustrative `appctl` command must be replaced by the application's real,
-reviewed jobs-main quiescence control.
+Set `VELOCIOUS_BACKGROUND_JOBS_LIFECYCLE_SOCKET` in the service environment to
+the release's reviewed lifecycle socket path.
 
 Each worker receives its generation's jobs-main port. Old workers keep that port
 for their entire lifetime; normal deploy draining never hands them to, or lets
@@ -43,23 +46,29 @@ them reconnect to, the new jobs-main. `replicas` scales the pool as
 
 1. Before activation, Rollbridge starts the candidate release's jobs-main and
    complete worker pool, then starts and health-checks the candidate web process.
-2. Activation switches new web traffic and makes the candidate jobs generation
-   active.
-3. The previous jobs generation retires as one unit. Its jobs-main stops schedule
+2. The previous jobs generation retires as one unit and acknowledges the exact
+   generation-scoped retirement command. Its jobs-main stops schedule
    ownership, new queue dispatch, and new ordinary worker handoffs. Its workers
    stop accepting handoffs.
-4. The old jobs-main stays running with its old workers. It continues owning
+3. The candidate acknowledges its exact generation-scoped activation command.
+4. Rollbridge synchronously commits the active release and proxy target.
+5. The old jobs-main stays running with its old workers. It continues owning
    their connections and heartbeats, lease fencing, terminal-report acceptance
    and acknowledgement, and durable store transitions. The old worker/reporting
    side durably retries terminal reports, tracks outstanding report promises,
    enforces per-job execution timeouts, and owns and reaps child runners.
-5. Work returned or retried to the shared queue becomes eligible for the new
+6. Work returned or retried to the shared queue becomes eligible for the new
    active generation. The retired main never dispatches it again.
-6. The old main and workers remain one release generation until every accepted
+7. The old main and workers remain one release generation until every accepted
    handoff settles. Only then, after every old worker drains and exits, may the
    old jobs-main exit. Rollbridge then reaps the generation and reports that its
    release reference ended so Rampway can release the retention pin.
 
+If the active jobs-main crashes or is manually restarted, Rollbridge restores its
+active role with the exact generation-scoped activation command before reporting
+the restarted process running. A retired generation remains fenced and is not
+auto-restarted.
+
 Old and new generations may overlap for hours, each running its own release code
 and jobs-main endpoint. Multiple retired generations may drain concurrently.
 

package/examples/tensorbuzz.com.js

@@ -2,9 +2,9 @@
 //
 // Nginx should keep proxying the backend host to 127.0.0.1:4500. Rollbridge
 // binds that stable HTTP port, forwards to the active release's internal web
-// port and keeps Beacon daemon-wide. The jobs-main and worker controls below
-// are illustrative: replace appctl with application commands that quiesce new
-// admission without terminating the generation.
+// port and keeps Beacon daemon-wide. The lifecycle socket path must match the
+// reviewed release-local Velocious jobs-main configuration; the worker appctl
+// command remains an illustrative application-specific quiescence control.
 
 export default {
   application: "tensorbuzz",
@@ -47,10 +47,14 @@ export default {
         NODE_ENV: "production",
         VELOCIOUS_ENV: "production",
         VELOCIOUS_BEACON_PORT: "{{ports.beacon}}",
-        VELOCIOUS_BACKGROUND_JOBS_PORT: "{{port}}"
+        VELOCIOUS_BACKGROUND_JOBS_PORT: "{{port}}",
+        VELOCIOUS_BACKGROUND_JOBS_LIFECYCLE_SOCKET: "{{releasePath}}/tmp/background-jobs-main.sock"
       },
       command: "wait-for-it 127.0.0.1:{{ports.beacon}} --strict -- npx velocious background-jobs-main",
-      lifecycle: {quietCommand: "appctl jobs-main-retire --pid $ROLLBRIDGE_PID"},
+      lifecycle: {
+        activateCommand: 'npx velocious background-jobs:activate --generation "$ROLLBRIDGE_RELEASE_ID" --socket "$VELOCIOUS_BACKGROUND_JOBS_LIFECYCLE_SOCKET"',
+        quietCommand: 'npx velocious background-jobs:retire --generation "$ROLLBRIDGE_RELEASE_ID" --socket "$VELOCIOUS_BACKGROUND_JOBS_LIFECYCLE_SOCKET"'
+      },
       port: {from: 7331, to: 7399}
     },
     {

package/package.json

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

package/src/config.js

@@ -14,7 +14,7 @@ import {pathToFileURL} from "node:url"
  * @typedef {"proxied" | "companion" | "singleton" | "service"} ProcessPolicy
  * @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 {{activateCommand?: string, drainCommand?: string, drainTimeoutMs: number, quietCommand?: string, stopCommand?: string}} LifecycleConfig
  * @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
@@ -158,6 +158,7 @@ export function validateConfig(rawConfig, configPath = process.cwd()) {
   if (ownerRecovery && !statePath) issues.push({fix: "Configure statePath when ownerRecovery is enabled.", message: "ownerRecovery requires statePath"})
 
   validateProcessSet(processes, issues)
+  validateActivationLifecycle(processes, ownerRecovery, statePath, issues)
 
   return {config: {application, control, legacyTakeover, ownerRecovery, processes, proxy, releaseRetention, statePath}, issues}
 }
@@ -341,7 +342,7 @@ function normalizeLifecycle(value, key, issues) {
   if (value === undefined || value === null) return {drainTimeoutMs: 0}
 
   if (!isPlainObject(value)) {
-    issues.push({fix: `Set ${key} to a mapping with optional quietCommand, drainCommand, stopCommand, and drainTimeoutMs.`, message: `${key} must be an object`})
+    issues.push({fix: `Set ${key} to a mapping with optional activateCommand, quietCommand, drainCommand, stopCommand, and drainTimeoutMs.`, message: `${key} must be an object`})
 
     return {drainTimeoutMs: 0}
   }
@@ -350,6 +351,7 @@ function normalizeLifecycle(value, key, issues) {
   /** @type {LifecycleConfig} */
   const lifecycle = {drainTimeoutMs: nonNegativeOrDefault(drainTimeoutMs, `${key}.drainTimeoutMs`, issues, 0, false)}
 
+  if (value.activateCommand !== undefined) lifecycle.activateCommand = normalizeString(value.activateCommand, `${key}.activateCommand`, issues)
   if (value.quietCommand !== undefined) lifecycle.quietCommand = normalizeString(value.quietCommand, `${key}.quietCommand`, issues)
   if (value.drainCommand !== undefined) lifecycle.drainCommand = normalizeString(value.drainCommand, `${key}.drainCommand`, issues)
   if (value.stopCommand !== undefined) lifecycle.stopCommand = normalizeString(value.stopCommand, `${key}.stopCommand`, issues)
@@ -361,6 +363,34 @@ function normalizeLifecycle(value, key, issues) {
   return lifecycle
 }
 
+/**
+ * Validates the opt-in durable generation activation contract.
+ * @param {ProcessConfig[]} processes - Normalized process definitions.
+ * @param {OwnerRecoveryConfig | undefined} ownerRecovery - Durable owner recovery config.
+ * @param {string | undefined} statePath - Durable state transaction anchor.
+ * @param {ConfigIssue[]} issues - Issue collector.
+ */
+function validateActivationLifecycle(processes, ownerRecovery, statePath, issues) {
+  const activated = processes.filter((processConfig) => processConfig.lifecycle.activateCommand !== undefined)
+
+  if (activated.length > 1) {
+    issues.push({fix: "Configure lifecycle.activateCommand on only one release-generation coordinator.", message: "Config may define at most one lifecycle.activateCommand"})
+  }
+
+  for (const processConfig of activated) {
+    if (processConfig.policy !== "service" || processConfig.deployStrategy !== "handoff") {
+      issues.push({fix: `Set lifecycle.activateCommand only on a service using deployStrategy: "handoff"; "${processConfig.id}" is ${processConfig.policy}/${processConfig.deployStrategy}.`, message: `Process "${processConfig.id}" can only set lifecycle.activateCommand on a handoff service`})
+    }
+    if (!processConfig.lifecycle.quietCommand) {
+      issues.push({fix: `Add lifecycle.quietCommand to "${processConfig.id}" so every activated generation has a paired retirement command.`, message: `Process "${processConfig.id}" lifecycle.activateCommand requires lifecycle.quietCommand`})
+    }
+  }
+
+  if (activated.length > 0 && (!ownerRecovery || !statePath)) {
+    issues.push({fix: "Configure statePath and ownerRecovery for durable release-generation transition recovery.", message: "lifecycle.activateCommand requires ownerRecovery and statePath"})
+  }
+}
+
 /**
  * @param {JsonValue} value - Raw legacy takeover config.
  * @param {ProxyConfig} proxy - Proxy config defaults.