rollbridge 0.1.40 → 0.1.41

package/examples/tensorbuzz.com.js

@@ -4,7 +4,7 @@
 // binds that stable HTTP port, forwards to the active release's internal web
 // 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.
+// commands remain illustrative application-specific quiescence/reactivation controls.
 
 export default {
   application: "tensorbuzz",
@@ -68,7 +68,10 @@ 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",
-      lifecycle: {quietCommand: "appctl jobs-worker-retire --pid $ROLLBRIDGE_PID"},
+      lifecycle: {
+        quietCommand: "appctl jobs-worker-retire --pid $ROLLBRIDGE_PID",
+        reactivateCommand: "appctl jobs-worker-reactivate --pid $ROLLBRIDGE_PID"
+      },
       nonBlockingDrain: true,
       gracefulStopMs: "indefinite"
     },

package/package.json

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

package/src/cli.js

@@ -213,6 +213,31 @@ export async function runCli(argv) {
       console.log(JSON.stringify(response, null, 2))
     })
 
+  program
+    .command("recover-generation-transition")
+    .description("Restore the exact incumbent and retire a failed pre-commit generation candidate.")
+    .option("-c, --config <path>", "Config file path (defaults to rollbridge.js)")
+    .requiredOption("--release-path <path>", "Failed candidate release path")
+    .requiredOption("--release-id <id>", "Failed candidate release id")
+    .requiredOption("--revision <sha>", "Failed candidate revision")
+    .requiredOption("--previous-release-id <id>", "Expected authoritative incumbent release id")
+    .action(async (options) => {
+      const configPath = await resolveConfigPath(options.config)
+      const config = await loadConfig(configPath)
+      const response = await sendControlCommand({
+        command: {
+          command: "recover-generation-transition",
+          previousReleaseId: options.previousReleaseId,
+          releaseId: options.releaseId,
+          releasePath: options.releasePath,
+          revision: options.revision
+        },
+        path: config.control.path
+      })
+
+      console.log(JSON.stringify(response, null, 2))
+    })
+
   program
     .command("ensure-daemon")
     .description("Start the daemon if the control socket is not already accepting commands.")

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 {{activateCommand?: string, drainCommand?: string, drainTimeoutMs: number, quietCommand?: string, stopCommand?: string}} LifecycleConfig
+ * @typedef {{activateCommand?: string, drainCommand?: string, drainTimeoutMs: number, quietCommand?: string, reactivateCommand?: 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
@@ -346,7 +346,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 activateCommand, quietCommand, drainCommand, stopCommand, and drainTimeoutMs.`, message: `${key} must be an object`})
+    issues.push({fix: `Set ${key} to a mapping with optional activateCommand, quietCommand, reactivateCommand, drainCommand, stopCommand, and drainTimeoutMs.`, message: `${key} must be an object`})
 
     return {drainTimeoutMs: 0}
   }
@@ -357,6 +357,7 @@ function normalizeLifecycle(value, key, issues) {
 
   if (value.activateCommand !== undefined) lifecycle.activateCommand = normalizeString(value.activateCommand, `${key}.activateCommand`, issues, {nonEmpty: true})
   if (value.quietCommand !== undefined) lifecycle.quietCommand = normalizeString(value.quietCommand, `${key}.quietCommand`, issues, {nonEmpty: true})
+  if (value.reactivateCommand !== undefined) lifecycle.reactivateCommand = normalizeString(value.reactivateCommand, `${key}.reactivateCommand`, issues, {nonEmpty: true})
   if (value.drainCommand !== undefined) lifecycle.drainCommand = normalizeString(value.drainCommand, `${key}.drainCommand`, issues, {nonEmpty: true})
   if (value.stopCommand !== undefined) lifecycle.stopCommand = normalizeString(value.stopCommand, `${key}.stopCommand`, issues, {nonEmpty: true})
 
@@ -376,6 +377,7 @@ function normalizeLifecycle(value, key, issues) {
  */
 function validateActivationLifecycle(processes, ownerRecovery, statePath, issues) {
   const activated = processes.filter((processConfig) => processConfig.lifecycle.activateCommand !== undefined)
+  const reactivated = processes.filter((processConfig) => processConfig.lifecycle.reactivateCommand !== 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"})
@@ -390,6 +392,23 @@ function validateActivationLifecycle(processes, ownerRecovery, statePath, issues
     }
   }
 
+  for (const processConfig of reactivated) {
+    if (processConfig.policy !== "companion" || !processConfig.nonBlockingDrain) {
+      issues.push({fix: `Set lifecycle.reactivateCommand only on a nonBlockingDrain companion; "${processConfig.id}" is ${processConfig.policy} with nonBlockingDrain: ${processConfig.nonBlockingDrain}.`, message: `Process "${processConfig.id}" can only set lifecycle.reactivateCommand on a nonBlockingDrain companion`})
+    }
+    if (!processConfig.lifecycle.quietCommand) {
+      issues.push({fix: `Add lifecycle.quietCommand to "${processConfig.id}" so worker reactivation has a paired retirement command.`, message: `Process "${processConfig.id}" lifecycle.reactivateCommand requires lifecycle.quietCommand`})
+    }
+  }
+
+  if (activated.length > 0) {
+    for (const processConfig of processes) {
+      if (processConfig.nonBlockingDrain && processConfig.lifecycle.quietCommand && !processConfig.lifecycle.reactivateCommand) {
+        issues.push({fix: `Add lifecycle.reactivateCommand to "${processConfig.id}" so failed candidate recovery reverses its external quiet hook.`, message: `Process "${processConfig.id}" lifecycle.quietCommand requires lifecycle.reactivateCommand during generation activation recovery`})
+      }
+    }
+  }
+
   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"})
   }

package/src/daemon.js

@@ -24,8 +24,8 @@ const STATE_PERSIST_INTERVAL_MS = 5000
  * @typedef {{attestation?: string, releaseId: string, releasePath: string, revision: string}} BootstrapIdentity
  * @typedef {{id: string, process: import("./managed-process.js").ManagedProcessStatus}} ProcessStatus
  * @typedef {{disruptive: true, mode: "legacy-first-upgrade", reason: string}} OwnerTransition
- * @typedef {"candidate_ready" | "retiring_previous" | "previous_retired" | "activating_candidate" | "committed_pending" | "committed" | "restoring_committed"} GenerationTransitionPhase
- * @typedef {{activationLifecycle?: boolean, candidateReleaseId: string, candidateReleasePath: string, candidateRevision: string, configDigest: string, error?: string, journalRevision?: number, phase: GenerationTransitionPhase, previousReleaseId: string | null, startedAt: string, updatedAt: string}} GenerationTransition
+ * @typedef {"candidate_ready" | "retiring_previous" | "previous_retired" | "activating_candidate" | "restoring_previous" | "retiring_failed_candidate" | "committed_pending" | "committed" | "restoring_committed"} GenerationTransitionPhase
+ * @typedef {{activationError?: string, activationLifecycle?: boolean, candidateReleaseId: string, candidateReleasePath: string, candidateRevision: string, compensationError?: string, configDigest: string, error?: string, journalRevision?: number, phase: GenerationTransitionPhase, previousReleaseId: string | null, startedAt: string, updatedAt: string}} GenerationTransition
  * @typedef {{activeReleaseId: string | null, application: string, bootstrap: BootstrapIdentity | undefined, control: import("./config.js").ControlConfig, daemonPid: number, daemonRuntime: import("./daemon-runtime.js").DaemonRuntimeIdentity | undefined, generationTransition?: GenerationTransition, ownerRecovery: {configDigest: string, ready: boolean} | undefined, ownerTransition?: OwnerTransition, orphans: {id: string, pid: number, releaseId: string | null}[], proxy: {host: string, port: number | undefined, upstreamHost: string}, releaseReferences: {releaseId: string, releasePath: string}[], releases: import("./release-group.js").ReleaseStatus[], services: ProcessStatus[], singletons: ProcessStatus[]}} DaemonStatus
  * @typedef {{configDigest: string, format: number, guardian: {pid?: number, socketPath: string, token: string}, reconnectGraceMs: number}} OwnerRecoveryMetadata
  * @typedef {DaemonStatus & {recovery: OwnerRecoveryMetadata, serviceReleaseIds?: Record<string, string>, singletonReleaseIds?: Record<string, string>}} OwnerRecoverySnapshot
@@ -1337,6 +1337,15 @@ export default class RollbridgeDaemon {
         }))
     }
 
+    if (commandName === "recover-generation-transition") {
+      return await this.executeOwnerMutation("recover generation transition", async () => await this.recoverGenerationTransition({
+        previousReleaseId: requiredString(data.previousReleaseId, "previousReleaseId"),
+        releaseId: requiredString(data.releaseId, "releaseId"),
+        releasePath: requiredString(data.releasePath, "releasePath"),
+        revision: requiredString(data.revision, "revision")
+      }))
+    }
+
     if (commandName === "status") {
       return this.status()
     }
@@ -1627,6 +1636,9 @@ export default class RollbridgeDaemon {
     const transition = this.generationTransition
 
     if (!transition) throw new Error("No release generation transition to resume")
+    if (transition.phase === "restoring_previous" || transition.phase === "retiring_failed_candidate") {
+      return await this.compensatePreCommitActivationFailure()
+    }
     const release = this.releases.get(transition.candidateReleaseId)
     const previousRelease = transition.previousReleaseId ? this.releases.get(transition.previousReleaseId) : undefined
 
@@ -1668,7 +1680,23 @@ export default class RollbridgeDaemon {
 
         await this.failGenerationTransition(failure)
         this.logger("release generation activation failed", {error: failure, releaseId: release.releaseId})
-        throw error
+        if (!previousRelease || !activationLifecycle) throw error
+
+        let compensation
+
+        try {
+          compensation = await this.compensatePreCommitActivationFailure()
+        } catch (compensationError) {
+          throw new AggregateError(
+            [error, compensationError],
+            `${failure}; pre-commit compensation failed: ${compensationError instanceof Error ? compensationError.message : String(compensationError)}`,
+            {cause: compensationError}
+          )
+        }
+        const compensatedError = /** @type {Error & {compensation?: Record<string, JsonValue>}} */ (new Error(`${failure}; compensation restored incumbent ${compensation.previousReleaseId} as authoritative and retired failed candidate ${compensation.candidateReleaseId}`, {cause: error}))
+
+        compensatedError.compensation = compensation
+        throw compensatedError
       }
 
       // Activation acknowledgement and the logical proxy commit deliberately share one
@@ -1732,6 +1760,155 @@ export default class RollbridgeDaemon {
     }
   }
 
+  /**
+   * Restores the authoritative proxy target and retires only the failed candidate.
+   * Every external effect is preceded by a durable phase checkpoint so recovery can
+   * safely replay the paired lifecycle hooks, which are already idempotent contracts.
+   * @returns {Promise<Record<string, JsonValue>>} Structured recovery result.
+   */
+  async compensatePreCommitActivationFailure() {
+    const transition = this.generationTransition
+
+    if (!transition) throw new Error("No release generation transition to compensate")
+    if (transition.phase !== "activating_candidate" && transition.phase !== "restoring_previous" && transition.phase !== "retiring_failed_candidate") {
+      throw new Error(`Generation transition ${transition.candidateReleaseId} at ${transition.phase} is not safe for pre-commit compensation`)
+    }
+    if (!transition.previousReleaseId) throw new Error("Pre-commit compensation requires a retained previous release")
+    const candidate = this.releases.get(transition.candidateReleaseId)
+    const previous = this.releases.get(transition.previousReleaseId)
+
+    if (!candidate) throw new Error(`Generation transition candidate ${transition.candidateReleaseId} is not retained`)
+    if (!previous) throw new Error(`Generation transition previous release ${transition.previousReleaseId} is not retained`)
+    if (this.activeRelease !== previous) throw new Error(`Previous release ${previous.releaseId} is not the authoritative proxy target`)
+
+    if (transition.phase === "activating_candidate") {
+      if (!transition.error && !transition.activationError) throw new Error("Candidate activation has no recorded failure to compensate")
+      transition.activationError = transition.activationError || transition.error
+      transition.compensationError = undefined
+      await this.updateGenerationTransition("retiring_failed_candidate")
+    }
+
+    if (transition.phase === "retiring_failed_candidate") {
+      try {
+        await candidate.beginRetirement(candidate.config, {retry: true})
+        const candidateServiceIds = [...this.serviceReleaseIds.entries()]
+          .filter(([, releaseId]) => releaseId === candidate.releaseId)
+          .map(([serviceId]) => serviceId)
+
+        await this.stopStartedServices(candidateServiceIds)
+      } catch (error) {
+        const failure = error instanceof Error ? error.message : String(error)
+
+        transition.compensationError = failure
+        await this.failGenerationTransition(`Failed candidate ${candidate.releaseId} retirement failed: ${failure}`)
+        this.logger("release generation compensation candidate retirement failed", {
+          activationError: transition.activationError,
+          error: failure,
+          releaseId: candidate.releaseId
+        })
+        throw new Error(`failed candidate ${candidate.releaseId} retirement failed: ${failure}`, {cause: error})
+      }
+      transition.compensationError = undefined
+      await this.updateGenerationTransition("restoring_previous")
+      this.logger("release generation compensation candidate retired", {releaseId: candidate.releaseId})
+    }
+
+    if (transition.phase === "restoring_previous") {
+      if (candidate.state !== "draining") throw new Error(`Failed candidate ${candidate.releaseId} is not retired before incumbent restoration`)
+      try {
+        await previous.reactivateGeneration()
+      } catch (error) {
+        const failure = error instanceof Error ? error.message : String(error)
+
+        transition.compensationError = failure
+        await this.failGenerationTransition(`Incumbent ${previous.releaseId} restoration failed: ${failure}`)
+        this.logger("release generation compensation restoration failed", {
+          activationError: transition.activationError,
+          error: failure,
+          releaseId: previous.releaseId
+        })
+        throw new Error(`incumbent ${previous.releaseId} restoration failed: ${failure}`, {cause: error})
+      }
+      this.activeRelease = previous
+      transition.compensationError = undefined
+      this.logger("release generation compensation incumbent restored", {releaseId: previous.releaseId})
+    }
+
+    const result = /** @type {Record<string, JsonValue>} */ ({
+      activeReleaseId: previous.releaseId,
+      activationError: transition.activationError,
+      candidateReleaseId: candidate.releaseId,
+      failedCandidateStatus: candidate.state,
+      previousReleaseId: previous.releaseId,
+      recoveryStatus: "recovered"
+    })
+
+    this.config = previous.config
+    this.generationTransition = undefined
+    try {
+      await this.checkpointGenerationTransition()
+    } catch (error) {
+      const failure = error instanceof Error ? error.message : String(error)
+
+      this.generationTransition = transition
+      transition.compensationError = failure
+      transition.error = `Compensation checkpoint clear failed: ${failure}`
+      transition.journalRevision = (transition.journalRevision ?? 0) + 1
+      transition.updatedAt = new Date().toISOString()
+      await this.publishOwnerState().catch((publishError) => {
+        this.logger("release generation compensation fence republish failed", {
+          error: publishError instanceof Error ? publishError.message : String(publishError),
+          releaseId: candidate.releaseId
+        })
+      })
+      this.logger("release generation compensation checkpoint failed", {error: failure, releaseId: candidate.releaseId})
+      throw new Error(`compensation checkpoint clear failed: ${failure}`, {cause: error})
+    }
+    void this.drainAndPrune(candidate, candidate.config)
+    this.logger("release generation compensation completed", result)
+    return result
+  }
+
+  /**
+   * Authenticated control recovery for one exact failed pre-commit transition.
+   * @param {{previousReleaseId: string, releaseId: string, releasePath: string, revision: string}} identity - Exact transition fence.
+   * @returns {Promise<Record<string, JsonValue>>} Structured recovery result.
+   */
+  async recoverGenerationTransition(identity) {
+    const transition = this.generationTransition
+
+    if (!transition) {
+      if (this.activeRelease?.releaseId !== identity.previousReleaseId || this.activeRelease.releaseId === identity.releaseId) {
+        throw new Error("No matching recovered generation transition; the expected incumbent is not authoritative")
+      }
+      return {
+        activeReleaseId: this.activeRelease.releaseId,
+        candidateReleaseId: identity.releaseId,
+        previousReleaseId: identity.previousReleaseId,
+        recoveryStatus: "already_recovered"
+      }
+    }
+    if (transition.previousReleaseId !== identity.previousReleaseId) {
+      throw new Error(`Generation transition previous release is ${transition.previousReleaseId}; refusing stale recovery for ${identity.previousReleaseId}`)
+    }
+    if (transition.phase !== "activating_candidate" && transition.phase !== "restoring_previous" && transition.phase !== "retiring_failed_candidate") {
+      throw new Error(`Generation transition ${transition.candidateReleaseId} at ${transition.phase} is not a safe failed pre-commit transition`)
+    }
+    const nextConfig = this.configPath ? await loadConfig(this.configPath) : this.config
+
+    this.assertReloadCompatible(nextConfig)
+    this.assertExactGenerationTransition(transition, {
+      config: nextConfig,
+      releaseId: identity.releaseId,
+      releasePath: identity.releasePath,
+      revision: identity.revision
+    })
+    if (this.activeRelease?.releaseId !== transition.previousReleaseId) {
+      throw new Error(`Previous release ${transition.previousReleaseId} is not the authoritative proxy target`)
+    }
+    return await this.compensatePreCommitActivationFailure()
+  }
+
   /**
    * @param {GenerationTransition} transition - Pending or committed exact transition.
    * @param {{config: import("./config.js").RollbridgeConfig, releaseId: string, releasePath: string, revision: string}} candidate - Requested identity.

package/src/guardian-client.js

@@ -23,6 +23,7 @@ export default class GuardianClient {
     this.processes = /** @type {Map<string, GuardianProcess>} */ (new Map())
     this.reservedProcessKey = /** @type {string | undefined} */ (undefined)
     this.reservedProcessProvenance = /** @type {string | undefined} */ (undefined)
+    this.generationReactivation = /** @type {boolean | undefined} */ (undefined)
     this.events = /** @type {Map<string, {reject: (error: Error) => void, resolve: (value: Record<string, import("./json.js").JsonValue>) => void}[]>} */ (new Map())
     this.eventHandlers = /** @type {Map<string, ((event: Record<string, import("./json.js").JsonValue>) => void)[]>} */ (new Map())
   }
@@ -51,6 +52,7 @@ export default class GuardianClient {
     if (child.connected) await new Promise((resolve) => child.once("disconnect", () => resolve(undefined)))
     child.unref()
     await this.connect()
+    this.generationReactivation = true
   }
 
   /**
@@ -184,9 +186,12 @@ export default class GuardianClient {
     await this.request({command: "owner-ready", ownerPid: process.pid})
   }
 
-  /** @returns {Promise<{daemonRecovery: number}>} Guardian protocol capabilities. */
+  /** @returns {Promise<{daemonRecovery: number, generationReactivation?: number}>} Guardian protocol capabilities. */
   async capabilities() {
-    return /** @type {{daemonRecovery: number}} */ (await this.request({command: "capabilities"}))
+    const capabilities = /** @type {{daemonRecovery: number, generationReactivation?: number}} */ (await this.request({command: "capabilities"}))
+
+    this.generationReactivation = capabilities.generationReactivation === 1
+    return capabilities
   }
 
   /** Starts graceful process retirement and relinquishes committed owner authority. */
@@ -445,6 +450,7 @@ class GuardianProcess extends ManagedProcess {
     this.cachedStatus = super.status()
     this.registration = /** @type {Promise<void> | undefined} */ (undefined)
     this.pendingUpdate = Promise.resolve()
+    this.compatibilityReactivated = false
   }
 
   async ensureRegistered() {
@@ -479,6 +485,7 @@ class GuardianProcess extends ManagedProcess {
     await this.pendingUpdate
     if (lifecycleRole) this.lifecycleRole = lifecycleRole
     this.cachedStatus = asProcessStatus(await this.client.request({command: "start", key: this.key, lifecycleRole, reason}))
+    if (this.cachedStatus.state === "running") this.compatibilityReactivated = false
   }
 
   /**
@@ -529,12 +536,52 @@ class GuardianProcess extends ManagedProcess {
     this.lifecycleRole = "active"
   }
 
+  async reactivateStrict() {
+    await this.ensureRegistered()
+    await this.pendingUpdate
+    const command = this.lifecycle.reactivateCommand ? "reactivate-with-command" : "reactivate"
+    try {
+      this.cachedStatus = asProcessStatus(await this.client.request({command, key: this.key}))
+      this.client.generationReactivation = true
+      this.compatibilityReactivated = false
+    } catch (error) {
+      if (!(error instanceof Error) || error.message !== `Unknown guardian command: ${command}`) throw error
+      this.client.generationReactivation = false
+      await this.adoptRetainedActive({activate: true})
+    }
+    this.lifecycleRole = "active"
+  }
+
+  /**
+   * Bridges a retained quiesced process owned by a pre-reactivation guardian.
+   * @param {{activate: boolean}} options - Whether to run the external activation acknowledgement.
+   */
+  async adoptRetainedActive({activate}) {
+    const before = this.cachedStatus
+
+    if (!before.pid || (before.state !== "quiesced" && before.state !== "running")) throw new Error(`Process ${this.id} is not retained for compatible reactivation`)
+    if (activate) await this.runReactivationHook(before.pid)
+    const verified = asProcessStatus(await this.client.request({command: "status", key: this.key}))
+
+    if (verified.pid !== before.pid || (verified.state !== "quiesced" && verified.state !== "running")) {
+      throw new Error(`Process ${this.id} exited before compatible reactivation completed`)
+    }
+    const adopted = asProcessStatus(await this.client.request({command: "start", key: this.key, lifecycleRole: "active", reason: "deploy"}))
+
+    if (adopted.pid !== before.pid) throw new Error(`Process ${this.id} changed before compatible reactivation was adopted`)
+    this.cachedStatus = asProcessStatus({...adopted, lifecycleRole: "active", state: "running"})
+    this.compatibilityReactivated = true
+  }
+
   /** @param {import("./managed-process.js").LifecycleRole} role - Exact generation role. */
   async setLifecycleRole(role) {
     await this.ensureRegistered()
     await this.pendingUpdate
     this.cachedStatus = asProcessStatus(await this.client.request({command: "set-lifecycle-role", key: this.key, lifecycleRole: role}))
     this.lifecycleRole = role
+    if (role === "active" && this.client.generationReactivation === false && this.cachedStatus.state === "quiesced") {
+      await this.adoptRetainedActive({activate: false})
+    }
   }
 
   async stop(options = {}) {
@@ -550,6 +597,12 @@ class GuardianProcess extends ManagedProcess {
   /** @param {Record<string, import("./json.js").JsonValue>} event - Guardian event. */
   onGuardianEvent(event) {
     if (event.status) this.cachedStatus = asProcessStatus(event.status)
+    if (this.compatibilityReactivated && (this.cachedStatus.state === "failed" || this.cachedStatus.state === "stopped") && this.shouldRestart()) {
+      this.compatibilityReactivated = false
+      void this.start("crash", this.lifecycleRole).catch((error) => {
+        this.logger("compatible reactivated process restart failed", {error: error instanceof Error ? error.message : String(error), id: this.id})
+      })
+    }
     if (event.event === "process-log") {
       const entry = asProcessLog(event.entry)
 

package/src/managed-process.js

@@ -486,14 +486,14 @@ export default class ManagedProcess extends EventEmitter {
       if (this.lifecycleRestoreBarrier) await this.lifecycleRestoreBarrier
       if (!this.child?.pid) {
         this.state = "stopped"
-        if (this.lifecycle.activateCommand) this.lifecycleRole = "retired"
+        if (this.hasRestorableLifecycle()) this.lifecycleRole = "retired"
         return
       }
       this.state = "stopping"
       if (this.lifecycle.quietCommand) this.quiesceError = await this.runHook(this.lifecycle.quietCommand, this.hookTimeoutMs(), "quiet command")
       if (!this.quiesceError) {
         this.state = "quiesced"
-        if (this.lifecycle.activateCommand) this.lifecycleRole = "retired"
+        if (this.hasRestorableLifecycle()) this.lifecycleRole = "retired"
       }
     })()
     return await this.quiescePromise
@@ -521,11 +521,63 @@ export default class ManagedProcess extends EventEmitter {
     const pid = this.pid
 
     if (!child?.pid || child.pid !== pid || this.state !== "running") throw new Error(`Process ${this.id} is not running for activation`)
+    await this.runActivationHook(pid)
+    if (this.child !== child || this.pid !== pid || this.state !== "running") throw new Error(`Process ${this.id} exited before activation completed`)
+    this.lifecycleRole = "active"
+  }
+
+  /** Reactivates an explicitly retired process without replacing its release-scoped process. */
+  async reactivateStrict() {
+    const child = this.child
+    const pid = this.pid
+
+    if (!child?.pid || child.pid !== pid || (this.state !== "quiesced" && this.state !== "running")) {
+      throw new Error(`Process ${this.id} is not retained for reactivation`)
+    }
+    await this.runReactivationHook(pid)
+    if (this.child !== child || this.pid !== pid) throw new Error(`Process ${this.id} exited before reactivation completed`)
+    this.intentionalStop = false
+    this.intentionalStopSignal = undefined
+    this.quiescePromise = undefined
+    this.quiesceError = undefined
+    this.state = "running"
+    this.lifecycleRole = "active"
+    this.startMemoryMonitor()
+  }
+
+  /**
+   * Runs the generation activation hook against one exact retained process.
+   * @param {number | undefined} pid - Exact process group leader.
+   * @returns {Promise<void>} Resolves after acknowledgement.
+   */
+  async runActivationHook(pid) {
+    const command = this.lifecycle.activateCommand
+
+    if (!command) return
     const error = await this.runHook(command, ACTIVATION_HOOK_TIMEOUT_MS, "activate command", pid)
 
     if (error) throw error
-    if (this.child !== child || this.pid !== pid || this.state !== "running") throw new Error(`Process ${this.id} exited before activation completed`)
-    this.lifecycleRole = "active"
+  }
+
+  /**
+   * Runs the process-specific reactivation hook, falling back to the generation
+   * coordinator's activation hook for the original lifecycle contract.
+   * @param {number | undefined} pid - Exact process group leader.
+   * @returns {Promise<void>} Resolves after acknowledgement.
+   */
+  async runReactivationHook(pid) {
+    const command = this.lifecycle.reactivateCommand ?? this.lifecycle.activateCommand
+
+    if (!command) return
+    const label = this.lifecycle.reactivateCommand ? "reactivate command" : "activate command"
+    const error = await this.runHook(command, ACTIVATION_HOOK_TIMEOUT_MS, label, pid)
+
+    if (error) throw error
+  }
+
+  /** @returns {boolean} Whether this process owns a durable external lifecycle role. */
+  hasRestorableLifecycle() {
+    return Boolean(this.lifecycle.activateCommand || this.lifecycle.reactivateCommand)
   }
 
   /**
@@ -538,12 +590,15 @@ export default class ManagedProcess extends EventEmitter {
 
   /** Restores an active or retired role after this exact process starts. */
   async restoreLifecycleRole() {
-    if (!this.lifecycle.activateCommand || this.lifecycleRole === "candidate") return
-    const command = this.lifecycleRole === "active" ? this.lifecycle.activateCommand : this.lifecycle.quietCommand
+    if (!this.hasRestorableLifecycle() || this.lifecycleRole === "candidate") return
+    const command = this.lifecycleRole === "active"
+      ? this.lifecycle.reactivateCommand ?? this.lifecycle.activateCommand
+      : this.lifecycle.quietCommand
 
     if (!command) throw new Error(`Process ${this.id} cannot restore lifecycle role ${this.lifecycleRole} without its paired command`)
     const timeoutMs = this.lifecycleRole === "active" ? ACTIVATION_HOOK_TIMEOUT_MS : this.hookTimeoutMs()
-    const error = await this.runHook(command, timeoutMs, `${this.lifecycleRole === "active" ? "activate" : "quiet"} command`, this.pid)
+    const activeLabel = this.lifecycle.reactivateCommand ? "reactivate" : "activate"
+    const error = await this.runHook(command, timeoutMs, `${this.lifecycleRole === "active" ? activeLabel : "quiet"} command`, this.pid)
 
     if (error) throw error
   }
@@ -760,7 +815,7 @@ export default class ManagedProcess extends EventEmitter {
       id: this.id,
       lastMemoryRestartAt: this.lastMemoryRestartAtMs === undefined ? undefined : new Date(this.lastMemoryRestartAtMs).toISOString(),
       lastStartReason: this.lastStartReason,
-      ...(this.lifecycle.activateCommand ? {lifecycleRole: this.lifecycleRole} : {}),
+      ...(this.hasRestorableLifecycle() ? {lifecycleRole: this.lifecycleRole} : {}),
       logs: this.logs.slice(-this.outputLines),
       memoryRestarts: this.memoryRestarts,
       pid: this.pid,

package/src/process-guardian.js

@@ -259,7 +259,7 @@ async function handleLine(socket, line) {
 async function execute(request, socket) {
   if (shuttingDown) throw new Error("Process guardian is shutting down")
 
-  if (request.command === "capabilities") return {daemonRecovery: 1}
+  if (request.command === "capabilities") return {daemonRecovery: 1, generationReactivation: 1}
 
   if (request.command === "owner-replacement-capabilities") {
     return {commands: ["commit-retired-owner-replacement"], protocol: "owner-replacement", version: 1}
@@ -655,6 +655,9 @@ async function execute(request, socket) {
     await record.process.start(request.reason, request.lifecycleRole)
   } else if (request.command === "activate") {
     await record.process.activateStrict()
+  } else if (request.command === "reactivate" || request.command === "reactivate-with-command") {
+    await record.process.reactivateStrict()
+    record.desired = true
   } else if (request.command === "quiesce") {
     record.desired = false
     await record.process.quiesceStrict()

package/src/release-group.js

@@ -279,6 +279,28 @@ export default class ReleaseGroup extends EventEmitter {
     await instance.process.activateStrict()
   }
 
+  /** Restores the retained generation coordinator to its active role in place. */
+  async reactivateGeneration() {
+    if (this.state !== "draining" && this.state !== "active") throw new Error(`Generation ${this.releaseId} is not retained for reactivation`)
+    const processConfig = this.config.processes.find((candidate) => candidate.lifecycle.activateCommand !== undefined)
+
+    if (!processConfig) throw new Error(`Generation ${this.releaseId} has no activation lifecycle`)
+    const [coordinator] = this.getProcesses(processConfig.id)
+
+    if (!coordinator) throw new Error(`Generation activation process ${processConfig.id} is not retained for release ${this.releaseId}`)
+    const generationIds = new Set([...this.handoffServiceIds, ...this.nonBlockingDrainIds])
+
+    for (const [id, processInstance] of this.processes) {
+      if (generationIds.has(id) && processInstance !== coordinator.process) await processInstance.reactivateStrict()
+    }
+    await coordinator.process.reactivateStrict()
+    this.state = "active"
+    this.activatedAt = new Date().toISOString()
+    this.drainStartedAt = undefined
+    this.retirementError = undefined
+    this.stoppedAt = undefined
+  }
+
   /**
    * Restarts only the exact processes reconstructed for a committed generation.
    * The caller must prove the durable transition identity before using this path.

package/test/completion.test.js

@@ -41,9 +41,10 @@ test("completion bash prints a sourceable script with commands and option flags"
 
   assert.notEqual(code, 1)
   assert.match(output, /complete -F _rollbridge rollbridge/)
-  assert.match(output, /compgen -W "daemon deploy rollback ensure-daemon status stop restart shutdown validate doctor logs events predeploy-cleanup recover completion"/)
+  assert.match(output, /compgen -W "daemon deploy rollback recover-generation-transition ensure-daemon status stop restart shutdown validate doctor logs events predeploy-cleanup recover completion"/)
   // A command's own options are completed after the command.
   assert.match(output, /deploy\)\n\s+opts="[^"]*--release-path[^"]*"/)
+  assert.match(output, /recover-generation-transition\)\n\s+opts="--config --release-path --release-id --revision --previous-release-id"/)
   assert.match(output, /ensure-daemon\)\n\s+opts="[^"]*--daemon-runtime-path[^"]*"/)
   assert.match(output, /restart\)\n\s+opts="[^"]*--policy[^"]*"/)
 })
@@ -53,7 +54,8 @@ test("completion zsh prints a #compdef script with per-command options", async (
 
   assert.match(output, /^#compdef rollbridge/)
   assert.match(output, /compdef _rollbridge rollbridge/)
-  assert.match(output, /commands=\(daemon deploy rollback ensure-daemon status stop restart shutdown validate doctor logs events predeploy-cleanup recover completion\)/)
+  assert.match(output, /commands=\(daemon deploy rollback recover-generation-transition ensure-daemon status stop restart shutdown validate doctor logs events predeploy-cleanup recover completion\)/)
+  assert.match(output, /recover-generation-transition\) compadd -- --config --release-path --release-id --revision --previous-release-id/)
   assert.match(output, /events\) compadd -- [^\n]*--limit/)
 })
 

package/test/config-examples.test.js

@@ -27,6 +27,7 @@ test("TensorBuzz example config loads", async () => {
       ["web", "proxied"]
     ]
   )
+  assert.equal(config.processes[2].lifecycle.reactivateCommand, "appctl jobs-worker-reactivate --pid $ROLLBRIDGE_PID")
   assert.equal(config.processes[3].env.VELOCIOUS_BACKGROUND_JOBS_PORT, "{{ports.background-jobs-main}}")
 })
 

package/test/config-validation.test.js

@@ -250,6 +250,24 @@ test("validateConfig accepts one durable handoff activation lifecycle and reject
     {...base.processes[1], id: "jobs-secondary", port: {from: 18200, to: 18299}}
   ]})
   assert.ok(duplicate.issues.some((issue) => /at most one lifecycle\.activateCommand/.test(issue.message)))
+
+  const worker = {
+    command: "run worker",
+    id: "worker",
+    lifecycle: {quietCommand: "worker quiet", reactivateCommand: "worker resume"},
+    nonBlockingDrain: true,
+    policy: "companion"
+  }
+  const pairedWorker = validateConfig({...base, processes: [...base.processes, worker]})
+
+  assert.deepEqual(pairedWorker.issues, [])
+  assert.equal(pairedWorker.config.processes[2].lifecycle.reactivateCommand, "worker resume")
+
+  const unpairedWorker = validateConfig({...base, processes: [...base.processes, {...worker, lifecycle: {quietCommand: "worker quiet"}}]})
+  assert.ok(unpairedWorker.issues.some((issue) => /quietCommand requires lifecycle\.reactivateCommand/.test(issue.message)))
+
+  const unsupportedPlacement = validateConfig({...base, processes: [...base.processes, {...worker, nonBlockingDrain: false}]})
+  assert.ok(unsupportedPlacement.issues.some((issue) => /reactivateCommand.*nonBlockingDrain companion/.test(issue.message)))
 })
 
 test("validateConfig accepts indefinite graceful stop windows", () => {

package/test/guardian-client.test.js

@@ -18,7 +18,7 @@ test("guardian bootstrap capability is absent from process argv", async () => {
   const fixture = await createGuardian()
 
   try {
-    assert.deepEqual(await fixture.client.capabilities(), {daemonRecovery: 1})
+    assert.deepEqual(await fixture.client.capabilities(), {daemonRecovery: 1, generationReactivation: 1})
     const commandLine = await fs.readFile(`/proc/${fixture.client.pid}/cmdline`, "utf8")
     const environment = await fs.readFile(`/proc/${fixture.client.pid}/environ`, "utf8")
     const status = await fs.readFile(`/proc/${fixture.client.pid}/status`, "utf8")
@@ -70,6 +70,87 @@ test("guardian runs a strict activation lifecycle command for the exact register
   }
 })
 
+test("client reactivates a retained process through a guardian without the reactivation command", async () => {
+  const fixture = await createGuardian()
+  const lifecyclePath = path.join(fixture.root, "lifecycle.log")
+  const processInstance = fixture.client.process("compatible-reactivation", {
+    ...definition("compatible-reactivation"),
+    lifecycle: {
+      activateCommand: `printf 'activate\n' >> ${JSON.stringify(lifecyclePath)}`,
+      drainTimeoutMs: 0,
+      quietCommand: `printf 'retire\n' >> ${JSON.stringify(lifecyclePath)}`
+    },
+    shouldRestart: () => true
+  })
+  const request = fixture.client.request.bind(fixture.client)
+
+  fixture.client.request = async command => {
+    if (command.command === "reactivate") throw new Error("Unknown guardian command: reactivate")
+    return await request(command)
+  }
+
+  try {
+    await processInstance.start()
+    await processInstance.activateStrict()
+    const pid = processInstance.status().pid
+
+    await processInstance.quiesceStrict()
+    await processInstance.reactivateStrict()
+
+    assert.equal(processInstance.status().pid, pid)
+    assert.equal(processInstance.status().state, "running")
+    assert.equal(processInstance.status().lifecycleRole, "active")
+    assert.equal(await fs.readFile(lifecyclePath, "utf8"), "activate\nretire\nactivate\n")
+
+    const restarted = once(processInstance, "started")
+
+    assert.ok(pid)
+    process.kill(-pid, "SIGKILL")
+    await restarted
+    assert.notEqual(processInstance.status().pid, pid)
+    assert.equal(processInstance.status().state, "running")
+    assert.equal(processInstance.status().lifecycleRole, "active")
+    assert.equal(await fs.readFile(lifecyclePath, "utf8"), "activate\nretire\nactivate\nactivate\n")
+  } finally {
+    await cleanupGuardian(fixture)
+  }
+})
+
+test("client reverses a worker quiet hook through a pre-reactivation guardian", async () => {
+  const fixture = await createGuardian()
+  const lifecyclePath = path.join(fixture.root, "worker-lifecycle.log")
+  const processInstance = fixture.client.process("compatible-worker-reactivation", {
+    ...definition("compatible-worker-reactivation"),
+    lifecycle: {
+      drainTimeoutMs: 0,
+      quietCommand: `printf 'quiet\n' >> ${JSON.stringify(lifecyclePath)}`,
+      reactivateCommand: `printf 'resume\n' >> ${JSON.stringify(lifecyclePath)}`
+    },
+    shouldRestart: () => true
+  })
+  const request = fixture.client.request.bind(fixture.client)
+
+  fixture.client.request = async command => {
+    if (command.command === "reactivate-with-command") throw new Error("Unknown guardian command: reactivate-with-command")
+    return await request(command)
+  }
+
+  try {
+    await processInstance.start()
+    const pid = processInstance.status().pid
+
+    await processInstance.quiesceStrict()
+    await processInstance.reactivateStrict()
+
+    assert.equal(processInstance.status().pid, pid)
+    assert.equal(processInstance.status().state, "running")
+    assert.equal(processInstance.status().lifecycleRole, "active")
+    assert.equal(await fs.readFile(lifecyclePath, "utf8"), "quiet\nresume\n")
+  } finally {
+    await cleanupGuardian(fixture)
+  }
+})
+
 test("guardian atomically updates process provenance with private owner state", async () => {
   const fixture = await createGuardian()
   const processInstance = fixture.client.process("service", definition("service"))

package/test/managed-process.test.js

@@ -505,6 +505,33 @@ test("activateStrict rejects an activation request when its process is not runni
   assert.equal(hookRan, false)
 })
 
+test("reactivateStrict restores a retained quiesced process only after activation succeeds", async () => {
+  const managed = buildLongLived(() => false)
+  const hooks = /** @type {string[]} */ ([])
+
+  managed.lifecycle = {activateCommand: "jobs activate", drainTimeoutMs: 0, quietCommand: "jobs retire"}
+  managed.runHook = async (_command, _timeoutMs, label) => {
+    hooks.push(label)
+    if (label === "activate command" && hooks.length === 2) return new Error("restoration rejected")
+    return undefined
+  }
+
+  try {
+    await managed.start()
+    await managed.quiesceStrict()
+    await assert.rejects(() => managed.reactivateStrict(), /restoration rejected/)
+    assert.equal(managed.status().state, "quiesced")
+    assert.equal(managed.status().lifecycleRole, "retired")
+
+    await managed.reactivateStrict()
+    assert.equal(managed.status().state, "running")
+    assert.equal(managed.status().lifecycleRole, "active")
+    assert.deepEqual(hooks, ["quiet command", "activate command", "activate command"])
+  } finally {
+    await managed.stop()
+  }
+})
+
 test("quiesce waits for active-role restoration before retiring a restarted process", async () => {
   const managed = buildLongLived(() => false)
   const hooks = /** @type {string[]} */ ([])

package/test/owner-recovery.test.js

@@ -748,7 +748,7 @@ test("guardian recovery becomes ready before replaying a gated generation hook",
   }
 })
 
-test("owner recovery preserves a failed generation transition without firing hooks until exact resume", async () => {
+test("owner recovery preserves a completed activation compensation without replaying hooks", async () => {
   const fixture = await createFixture({activationFailureRelease: "v2"})
   let owner = spawnDaemon(fixture.configPath)
 
@@ -762,7 +762,7 @@ test("owner recovery preserves a failed generation transition without firing hoo
       sendControlCommand({command: {command: "deploy", releaseId: "v2", releasePath: v2Path, revision: "v2"}, path: fixture.socketPath}),
       /activate command exited non-zero/
     )
-    assert.deepEqual(await lifecycleEvents(fixture.lifecycleLogPath), ["activate:v1", "retire:v1"])
+    assert.deepEqual(await lifecycleEvents(fixture.lifecycleLogPath), ["activate:v1", "retire:v1", "retire:v2", "activate:v1"])
 
     owner.kill("SIGKILL")
     await once(owner, "exit")
@@ -771,13 +771,9 @@ test("owner recovery preserves a failed generation transition without firing hoo
 
     const recovered = /** @type {DaemonStatus} */ (await sendControlCommand({command: {command: "status"}, path: fixture.socketPath}))
 
-    assert.equal(recovered.generationTransition?.phase, "activating_candidate")
-    assert.match(String(recovered.generationTransition?.error), /activate command exited non-zero/)
-    assert.deepEqual(await lifecycleEvents(fixture.lifecycleLogPath), ["activate:v1", "retire:v1"], "owner recovery alone must not retry a failed hook")
-
-    await fs.writeFile(fixture.activationGatePath, "allow\n")
-    await sendControlCommand({command: {command: "deploy", releaseId: "v2", releasePath: v2Path, revision: "v2"}, path: fixture.socketPath})
-    assert.deepEqual(await lifecycleEvents(fixture.lifecycleLogPath), ["activate:v1", "retire:v1", "activate:v2"])
+    assert.equal(recovered.activeReleaseId, "v1")
+    assert.equal(recovered.generationTransition, undefined)
+    assert.deepEqual(await lifecycleEvents(fixture.lifecycleLogPath), ["activate:v1", "retire:v1", "retire:v2", "activate:v1"], "owner recovery must not replay completed compensation hooks")
 
     const shutdown = sendControlCommand({command: {command: "shutdown"}, path: fixture.socketPath})
     await Promise.all([v1Path, v2Path].map((releasePath) => fs.writeFile(path.join(releasePath, "worker.fifo"), "drained\n")))
@@ -789,17 +785,14 @@ test("owner recovery preserves a failed generation transition without firing hoo
   }
 })
 
-test("owner recovery replays one journaled ambiguous activation by exact generation identity", async () => {
-  const fixture = await createFixture({activationFailureRelease: "v2"})
+test("owner recovery replays one journaled ambiguous first-generation activation by exact identity", async () => {
+  const fixture = await createFixture({activationFailureRelease: "v1"})
   let owner = spawnDaemon(fixture.configPath)
 
   try {
     await waitForLog(owner, "control socket listening")
     const v1Path = await prepareRelease(fixture.root, "v1")
-    const v2Path = await prepareRelease(fixture.root, "v2")
-
-    await sendControlCommand({command: {command: "deploy", releaseId: "v1", releasePath: v1Path, revision: "v1"}, path: fixture.socketPath})
-    await assert.rejects(sendControlCommand({command: {command: "deploy", releaseId: "v2", releasePath: v2Path, revision: "v2"}, path: fixture.socketPath}))
+    await assert.rejects(sendControlCommand({command: {command: "deploy", releaseId: "v1", releasePath: v1Path, revision: "v1"}, path: fixture.socketPath}))
     owner.kill("SIGKILL")
     await once(owner, "exit")
 
@@ -818,12 +811,12 @@ test("owner recovery replays one journaled ambiguous activation by exact generat
 
     const recovered = /** @type {DaemonStatus} */ (await sendControlCommand({command: {command: "status"}, path: fixture.socketPath}))
 
-    assert.equal(recovered.activeReleaseId, "v2")
+    assert.equal(recovered.activeReleaseId, "v1")
     assert.equal(recovered.generationTransition?.phase, "committed")
-    assert.deepEqual(await lifecycleEvents(fixture.lifecycleLogPath), ["activate:v1", "retire:v1", "activate:v2"])
+    assert.deepEqual(await lifecycleEvents(fixture.lifecycleLogPath), ["activate:v1"])
 
     const shutdown = sendControlCommand({command: {command: "shutdown"}, path: fixture.socketPath})
-    await Promise.all([v1Path, v2Path].map((releasePath) => fs.writeFile(path.join(releasePath, "worker.fifo"), "drained\n")))
+    await fs.writeFile(path.join(v1Path, "worker.fifo"), "drained\n")
     await shutdown
   } finally {
     await killChild(owner)

package/test/owner-replacement.test.js

@@ -1649,7 +1649,7 @@ test("pruned release connection completion closes the incumbent listener session
   assert.equal(daemon.incumbentListenerControl, session)
 })
 
-test("same-authority owner replacement preserves a failed generation transition without retrying its hook", async () => {
+test("same-authority owner replacement preserves completed activation compensation without replaying hooks", async () => {
   const root = await fs.mkdtemp(path.join(os.tmpdir(), "rollbridge-owner-replacement-failed-generation-"))
   const oldSocketPath = path.join(root, "old.sock")
   const statePath = path.join(root, "state.json")
@@ -1677,18 +1677,15 @@ test("same-authority owner replacement preserves a failed generation transition
     await waitForLog(owner, "control socket listening")
     await sendControlCommand({command: {command: "deploy", releaseId: "v1", releasePath: v1Path, revision: "v1"}, path: oldSocketPath})
     await assert.rejects(sendControlCommand({command: {command: "deploy", releaseId: "v2", releasePath: v2Path, revision: "v2"}, path: oldSocketPath}), /activate command exited non-zero/)
-    assert.equal(await fs.readFile(lifecycleLogPath, "utf8"), "activate:v1\nretire:v1\n")
+    assert.equal(await fs.readFile(lifecycleLogPath, "utf8"), "activate:v1\nretire:v1\nretire:v2\nactivate:v1\n")
 
     await writeConfig(configPath, failedConfig(oldSocketPath, false))
     candidate = spawn(process.execPath, [binPath, "daemon", "--config", configPath, "--replace-owner"], {stdio: ["ignore", "pipe", "pipe"]})
     await waitForLog(candidate, "owner replacement committed")
     const status = await sendControlCommand({command: {command: "status"}, path: oldSocketPath})
-    const generationTransition = status.generationTransition
-
-    assert.ok(generationTransition && typeof generationTransition === "object" && !Array.isArray(generationTransition))
-    assert.equal(generationTransition.phase, "activating_candidate")
-    assert.match(String(generationTransition.error), /activate command exited non-zero/)
-    assert.equal(await fs.readFile(lifecycleLogPath, "utf8"), "activate:v1\nretire:v1\n", "replacement must preserve, not retry, the failed activation")
+    assert.equal(status.activeReleaseId, "v1")
+    assert.equal(status.generationTransition, undefined)
+    assert.equal(await fs.readFile(lifecycleLogPath, "utf8"), "activate:v1\nretire:v1\nretire:v2\nactivate:v1\n", "replacement must not replay completed compensation hooks")
 
     const shutdown = sendControlCommand({command: {command: "shutdown"}, path: oldSocketPath})
     await Promise.all([v1Path, v2Path].map((releasePath) => fs.writeFile(path.join(releasePath, "worker.fifo"), "drained\n")))
@@ -1700,7 +1697,7 @@ test("same-authority owner replacement preserves a failed generation transition
   }
 })
 
-test("config-changing owner replacement rejects an unresolved generation transition", async () => {
+test("config-changing owner replacement proceeds after activation compensation clears the transition", async () => {
   const root = await fs.mkdtemp(path.join(os.tmpdir(), "rollbridge-owner-replacement-unresolved-config-"))
   const oldSocketPath = path.join(root, "old.sock")
   const newSocketPath = path.join(root, "new.sock")
@@ -1734,16 +1731,13 @@ test("config-changing owner replacement rejects an unresolved generation transit
     candidate = spawn(process.execPath, [binPath, "daemon", "--config", configPath, "--replace-owner"], {stdio: ["ignore", "pipe", "pipe"]})
     const result = await collectUntilExitOrLog(candidate, "owner replacement committed")
 
-    assert.equal(result.message, undefined, result.output)
-    assert.match(result.output, /config authority.*unresolved generation transition/i)
-    const status = await sendControlCommand({command: {command: "status"}, path: oldSocketPath})
-    const generationTransition = status.generationTransition
+    assert.equal(result.message, "owner replacement committed", result.output)
+    const status = await sendControlCommand({command: {command: "status"}, path: newSocketPath})
 
-    assert.ok(generationTransition && typeof generationTransition === "object" && !Array.isArray(generationTransition))
-    assert.equal(generationTransition.phase, "activating_candidate")
-    assert.match(String(generationTransition.error), /activate command exited non-zero/)
-    assert.equal(await fs.readFile(lifecycleLogPath, "utf8"), "activate:v1\nretire:v1\n")
-    const shutdown = sendControlCommand({command: {command: "shutdown"}, path: oldSocketPath})
+    assert.equal(status.activeReleaseId, "v1")
+    assert.equal(status.generationTransition, undefined)
+    assert.equal(await fs.readFile(lifecycleLogPath, "utf8"), "activate:v1\nretire:v1\nretire:v2\nactivate:v1\n")
+    const shutdown = sendControlCommand({command: {command: "shutdown"}, path: newSocketPath})
 
     await Promise.all([v1Path, v2Path].map((releasePath) => fs.writeFile(path.join(releasePath, "worker.fifo"), "drained\n")))
     await shutdown
@@ -1928,7 +1922,7 @@ async function removeDaemonRecoveryCapability(packagePath, {abortedPath, prepare
   const guardianPath = path.join(packagePath, "src", "process-guardian.js")
   const daemonPath = path.join(packagePath, "src", "daemon.js")
   const source = await fs.readFile(guardianPath, "utf8")
-  const capability = "  if (request.command === \"capabilities\") return {daemonRecovery: 1}\n\n"
+  const capability = "  if (request.command === \"capabilities\") return {daemonRecovery: 1, generationReactivation: 1}\n\n"
   const incumbentAbortNotification = "  if (ownerClient && !ownerClient.destroyed) ownerClient.write(`${JSON.stringify({event: \"replacement-aborted\", reason})}\\n`)\n"
   const legacyCapability = `  if (request.command === "capabilities") {
     while (!fsSync.existsSync(${JSON.stringify(preparedPath)})) await new Promise((resolve) => setTimeout(resolve, 5))

package/test/rollbridge.test.js

@@ -660,25 +660,248 @@ test("retirement failure retains the exact transition, blocks other deploys, and
   }
 })
 
-test("candidate activation failure never reactivates old and exact resume activates only the candidate", async () => {
+test("candidate activation failure reports restoration failure and exact recovery clears the fence", async () => {
   const fixture = await createFixture({handoffService: true, handoffServiceActivate: true, handoffServiceActivateFailure: true, nonBlockingDrainWorker: true, webDependsOnService: true})
   const daemon = await startDaemon(fixture.config)
 
   try {
     await daemon.deploy({releaseId: "v1", releasePath: fixture.root, revision: "v1"})
-    await assert.rejects(() => daemon.deploy({releaseId: "v2", releasePath: fixture.root, revision: "v2"}), /activate command exited non-zero/)
+    const incumbentCoordinator = daemon.releases.get("v1")?.getProcess("beacon")
+    const reactivate = incumbentCoordinator?.reactivateStrict.bind(incumbentCoordinator)
+
+    assert.ok(incumbentCoordinator && reactivate)
+    incumbentCoordinator.reactivateStrict = async () => { throw new Error("incumbent restoration rejected") }
+    await assert.rejects(
+      () => daemon.deploy({releaseId: "v2", releasePath: fixture.root, revision: "v2"}),
+      error => {
+        assert.ok(error instanceof AggregateError)
+        assert.match(error.message, /activate command exited non-zero/)
+        assert.match(error.message, /incumbent v1 restoration failed: incumbent restoration rejected/i)
+        return true
+      }
+    )
 
     const failed = daemon.status()
 
     assert.equal(failed.activeReleaseId, "v1")
-    assert.equal(failed.generationTransition?.phase, "activating_candidate")
-    assert.deepEqual(await lifecycleEvents(fixture.lifecycleLogPath), ["activate:v1", "retire:v1"])
+    assert.equal(failed.generationTransition?.phase, "restoring_previous")
+    assert.match(String(failed.generationTransition?.activationError), /activate command exited non-zero/)
+    assert.match(String(failed.generationTransition?.compensationError), /incumbent restoration rejected/)
+    const failedEvents = daemon.eventLog.recent()
+    const activationEvent = failedEvents.find((event) => event.message === "release generation activation failed")
+    const restorationEvent = failedEvents.find((event) => event.message === "release generation compensation restoration failed")
+
+    assert.match(String(activationEvent?.data.error), /activate command exited non-zero/)
+    assert.match(String(restorationEvent?.data.activationError), /activate command exited non-zero/)
+    assert.match(String(restorationEvent?.data.error), /incumbent restoration rejected/)
+    assert.deepEqual(await lifecycleEvents(fixture.lifecycleLogPath), ["activate:v1", "retire:v1", "retire:v2"])
+    await assert.rejects(() => daemon.deploy({releaseId: "v3", releasePath: fixture.root, revision: "v3"}), /transition.*v2.*unresolved/i)
 
-    await fs.writeFile(fixture.activationGatePath, "allow\n")
-    await daemon.deploy({releaseId: "v2", releasePath: fixture.root, revision: "v2"})
+    incumbentCoordinator.reactivateStrict = reactivate
+    const recovery = await sendControlCommand({
+      command: {
+        command: "recover-generation-transition",
+        previousReleaseId: "v1",
+        releaseId: "v2",
+        releasePath: fixture.root,
+        revision: "v2"
+      },
+      path: fixture.config.control.path
+    })
 
-    assert.equal(daemon.status().activeReleaseId, "v2")
-    assert.deepEqual(await lifecycleEvents(fixture.lifecycleLogPath), ["activate:v1", "retire:v1", "activate:v2"])
+    assert.equal(recovery.recoveryStatus, "recovered")
+    assert.equal(daemon.status().activeReleaseId, "v1")
+    assert.equal(daemon.status().generationTransition, undefined)
+    const persisted = /** @type {{generationTransition?: import("../src/json.js").JsonValue} | undefined} */ (await readState(fixture.statePath))
+
+    assert.equal(persisted?.generationTransition, undefined)
+    assert.deepEqual(await lifecycleEvents(fixture.lifecycleLogPath), ["activate:v1", "retire:v1", "retire:v2", "activate:v1"])
+
+    const idempotent = await sendControlCommand({
+      command: {
+        command: "recover-generation-transition",
+        previousReleaseId: "v1",
+        releaseId: "v2",
+        releasePath: fixture.root,
+        revision: "v2"
+      },
+      path: fixture.config.control.path
+    })
+
+    assert.equal(idempotent.recoveryStatus, "already_recovered")
+    await daemon.deploy({releaseId: "v3", releasePath: fixture.root, revision: "v3"})
+    await assert.rejects(
+      () => sendControlCommand({
+        command: {
+          command: "recover-generation-transition",
+          previousReleaseId: "v1",
+          releaseId: "v3",
+          releasePath: fixture.root,
+          revision: "v3"
+        },
+        path: fixture.config.control.path
+      }),
+      /not a safe failed pre-commit transition/i
+    )
+  } finally {
+    await daemon.shutdown()
+    await fs.rm(fixture.root, {force: true, recursive: true})
+  }
+})
+
+test("candidate activation failure compensates to the incumbent and admits a different later release", async () => {
+  const fixture = await createFixture({handoffService: true, handoffServiceActivate: true, handoffServiceActivateFailure: true, nonBlockingDrainWorker: true, webDependsOnService: true})
+  const daemon = await startDaemon(fixture.config)
+
+  try {
+    await daemon.deploy({releaseId: "v1", releasePath: fixture.root, revision: "v1"})
+    await assert.rejects(
+      () => daemon.deploy({releaseId: "v2", releasePath: fixture.root, revision: "v2"}),
+      /activate command exited non-zero.*compensation restored incumbent v1 as authoritative and retired failed candidate v2/i
+    )
+
+    const compensated = daemon.status()
+
+    assert.equal(compensated.activeReleaseId, "v1")
+    assert.equal(compensated.generationTransition, undefined)
+    assert.equal(await fetchText(daemon, "/release"), "v1")
+    assert.equal(statusRelease(daemon, "v1").processes.find((processStatus) => processStatus.id === "worker")?.state, "running")
+    assert.deepEqual(await lifecycleEvents(fixture.lifecycleLogPath), ["activate:v1", "retire:v1", "retire:v2", "activate:v1"])
+
+    await daemon.deploy({releaseId: "v3", releasePath: fixture.root, revision: "v3"})
+
+    assert.equal(daemon.status().activeReleaseId, "v3")
+    assert.equal(await fetchText(daemon, "/release"), "v3")
+  } finally {
+    await daemon.shutdown()
+    await fs.rm(fixture.root, {force: true, recursive: true})
+  }
+})
+
+test("ambiguous candidate activation retires the candidate before reactivating the incumbent", async () => {
+  const fixture = await createFixture({handoffService: true, handoffServiceActivate: true, handoffServiceActivateAmbiguousFailure: true, nonBlockingDrainWorker: true, webDependsOnService: true})
+  const daemon = await startDaemon(fixture.config)
+
+  try {
+    await daemon.deploy({releaseId: "v1", releasePath: fixture.root, revision: "v1"})
+    await assert.rejects(
+      () => daemon.deploy({releaseId: "v2", releasePath: fixture.root, revision: "v2"}),
+      /activate command exited non-zero.*compensation restored incumbent v1 as authoritative and retired failed candidate v2/i
+    )
+
+    assert.deepEqual(await lifecycleEvents(fixture.lifecycleLogPath), [
+      "activate:v1",
+      "retire:v1",
+      "activate:v2",
+      "retire:v2",
+      "activate:v1"
+    ])
+    assert.equal(daemon.status().activeReleaseId, "v1")
+    assert.equal(daemon.status().generationTransition, undefined)
+  } finally {
+    await daemon.shutdown()
+    await fs.rm(fixture.root, {force: true, recursive: true})
+  }
+})
+
+test("candidate activation recovery reverses a worker-specific quiet hook before reporting active", async () => {
+  const fixture = await createFixture({handoffService: true, handoffServiceActivate: true, handoffServiceActivateFailure: true, nonBlockingDrainWorker: true, webDependsOnService: true, workerReactivationLifecycle: true})
+  const daemon = await startDaemon(fixture.config)
+
+  try {
+    await daemon.deploy({releaseId: "v1", releasePath: fixture.root, revision: "v1"})
+    await assert.rejects(
+      () => daemon.deploy({releaseId: "v2", releasePath: fixture.root, revision: "v2"}),
+      /compensation restored incumbent v1 as authoritative/i
+    )
+
+    const events = await lifecycleEvents(fixture.lifecycleLogPath)
+    const candidateRetired = events.indexOf("worker-retire:v2")
+    const workerReactivated = events.indexOf("worker-reactivate:v1")
+
+    assert.ok(candidateRetired >= 0, JSON.stringify(events))
+    assert.ok(workerReactivated > candidateRetired, JSON.stringify(events))
+    assert.equal(statusRelease(daemon, "v1").processes.find((processStatus) => processStatus.id === "worker")?.state, "running")
+    assert.equal(daemon.status().activeReleaseId, "v1")
+    assert.equal(daemon.status().generationTransition, undefined)
+  } finally {
+    await daemon.shutdown()
+    await fs.rm(fixture.root, {force: true, recursive: true})
+  }
+})
+
+test("candidate activation recovery keeps the fence when a worker-specific resume hook fails", async () => {
+  const fixture = await createFixture({handoffService: true, handoffServiceActivate: true, handoffServiceActivateFailure: true, nonBlockingDrainWorker: true, webDependsOnService: true, workerReactivationFailure: true, workerReactivationLifecycle: true})
+  const daemon = await startDaemon(fixture.config)
+
+  try {
+    await daemon.deploy({releaseId: "v1", releasePath: fixture.root, revision: "v1"})
+    await assert.rejects(
+      () => daemon.deploy({releaseId: "v2", releasePath: fixture.root, revision: "v2"}),
+      error => {
+        const failure = /** @type {Error} */ (error)
+
+        assert.match(failure.message, /activate command exited non-zero/)
+        assert.match(failure.message, /reactivate command exited non-zero/)
+        return true
+      }
+    )
+
+    const status = daemon.status()
+    const restorationEvent = daemon.eventLog.recent().find((event) => event.message === "release generation compensation restoration failed")
+
+    assert.equal(status.activeReleaseId, "v1")
+    assert.equal(status.generationTransition?.phase, "restoring_previous")
+    assert.match(String(status.generationTransition?.activationError), /activate command exited non-zero/)
+    assert.match(String(status.generationTransition?.compensationError), /reactivate command exited non-zero/)
+    assert.equal(statusRelease(daemon, "v1").processes.find((processStatus) => processStatus.id === "worker")?.state, "quiesced")
+    assert.match(String(restorationEvent?.data.activationError), /activate command exited non-zero/)
+    assert.match(String(restorationEvent?.data.error), /reactivate command exited non-zero/)
+    await assert.rejects(() => daemon.deploy({releaseId: "v3", releasePath: fixture.root, revision: "v3"}), /transition.*v2.*unresolved/i)
+  } finally {
+    await daemon.shutdown()
+    await fs.rm(fixture.root, {force: true, recursive: true})
+  }
+})
+
+test("compensation keeps the fence when the cleared checkpoint cannot be persisted", async () => {
+  const fixture = await createFixture({handoffService: true, handoffServiceActivate: true, handoffServiceActivateFailure: true, nonBlockingDrainWorker: true, webDependsOnService: true})
+  const daemon = await startDaemon(fixture.config)
+
+  try {
+    await daemon.deploy({releaseId: "v1", releasePath: fixture.root, revision: "v1"})
+    const checkpoint = daemon.checkpointGenerationTransition.bind(daemon)
+
+    daemon.checkpointGenerationTransition = async () => {
+      if (!daemon.generationTransition) throw new Error("cleared checkpoint unavailable")
+      await checkpoint()
+    }
+    await assert.rejects(
+      () => daemon.deploy({releaseId: "v2", releasePath: fixture.root, revision: "v2"}),
+      /activate command exited non-zero.*compensation checkpoint clear failed: cleared checkpoint unavailable/i
+    )
+
+    assert.equal(daemon.status().activeReleaseId, "v1")
+    assert.equal(daemon.status().generationTransition?.phase, "restoring_previous")
+    const persisted = /** @type {{generationTransition?: {phase?: string}} | undefined} */ (await readState(fixture.statePath))
+
+    assert.equal(persisted?.generationTransition?.phase, "restoring_previous")
+    await assert.rejects(() => daemon.deploy({releaseId: "v3", releasePath: fixture.root, revision: "v3"}), /transition.*v2.*unresolved/i)
+
+    daemon.checkpointGenerationTransition = checkpoint
+    const recovery = await sendControlCommand({
+      command: {
+        command: "recover-generation-transition",
+        previousReleaseId: "v1",
+        releaseId: "v2",
+        releasePath: fixture.root,
+        revision: "v2"
+      },
+      path: fixture.config.control.path
+    })
+
+    assert.equal(recovery.recoveryStatus, "recovered")
+    assert.equal(daemon.status().generationTransition, undefined)
   } finally {
     await daemon.shutdown()
     await fs.rm(fixture.root, {force: true, recursive: true})
@@ -691,6 +914,10 @@ test("unresolved generation transition fences stop, restart, and rollback mutati
 
   try {
     await daemon.deploy({releaseId: "v1", releasePath: fixture.root, revision: "v1"})
+    const incumbentCoordinator = daemon.releases.get("v1")?.getProcess("beacon")
+
+    assert.ok(incumbentCoordinator)
+    incumbentCoordinator.reactivateStrict = async () => { throw new Error("incumbent restoration rejected") }
     await assert.rejects(() => daemon.deploy({releaseId: "v2", releasePath: fixture.root, revision: "v2"}), /activate command exited non-zero/)
 
     await assert.rejects(() => daemon.stopRelease("v2"), /cannot stop.*generation transition.*unresolved/i)
@@ -698,9 +925,7 @@ test("unresolved generation transition fences stop, restart, and rollback mutati
     await assert.rejects(() => daemon.rollback({releaseId: "v2"}), /cannot rollback.*generation transition.*unresolved/i)
 
     assert.notEqual(statusRelease(daemon, "v2").processes.find((entry) => entry.id === "web")?.state, "stopped")
-    await fs.writeFile(fixture.activationGatePath, "allow\n")
-    await daemon.deploy({releaseId: "v2", releasePath: fixture.root, revision: "v2"})
-    assert.equal(await fetchText(daemon, "/release"), "v2")
+    assert.equal(await fetchText(daemon, "/release"), "v1")
   } finally {
     await daemon.shutdown()
     await fs.rm(fixture.root, {force: true, recursive: true})
@@ -1654,7 +1879,7 @@ test("deploy can ensure the daemon before sending the release command", async ()
 })
 
 /**
- * @param {{companionReplicas?: number, handoffService?: boolean, handoffServiceActivate?: boolean, handoffServiceActivateFailure?: boolean | string, handoffServiceQuiet?: boolean, handoffServiceQuietFailure?: 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.
+ * @param {{companionReplicas?: number, handoffService?: boolean, handoffServiceActivate?: boolean, handoffServiceActivateAmbiguousFailure?: boolean, handoffServiceActivateFailure?: boolean | string, handoffServiceQuiet?: boolean, handoffServiceQuietFailure?: boolean, includeCompanion?: boolean, includeService?: boolean, includeSingleton?: boolean, memoryLimitBytes?: number, nonBlockingDrainWorker?: boolean, persistState?: boolean, proxyHost?: string, singletonCwd?: string, webCommand?: string, webDependsOnService?: boolean, webHealthTimeoutMs?: number, workerReactivationFailure?: boolean, workerReactivationLifecycle?: boolean, workerStopDelayMs?: number}} [options] - Fixture options.
  * @returns {Promise<{activationGatePath: string, config: import("../src/config.js").RollbridgeConfig, lifecycleLogPath: string, retirementGatePath: string, root: string, serviceLogPath: string, serviceQuietPath: string, singletonLogPath: string, statePath: string}>} Fixture data.
  */
 async function createFixture(options = {}) {
@@ -1672,7 +1897,7 @@ async function createFixture(options = {}) {
   if (options.includeService || options.handoffService) {
     const activationFailureRelease = typeof options.handoffServiceActivateFailure === "string" ? options.handoffServiceActivateFailure : "v2"
     const lifecycle = options.handoffServiceActivate ? {
-      activateCommand: `${options.handoffServiceActivateFailure ? `[ "$ROLLBRIDGE_RELEASE_ID" != ${JSON.stringify(activationFailureRelease)} ] || [ -f ${JSON.stringify(activationGatePath)} ] || exit 24; ` : ""}printf 'activate:%s\\n' "$ROLLBRIDGE_RELEASE_ID" >> ${JSON.stringify(lifecycleLogPath)}`,
+      activateCommand: `${options.handoffServiceActivateFailure && !options.handoffServiceActivateAmbiguousFailure ? `[ "$ROLLBRIDGE_RELEASE_ID" != ${JSON.stringify(activationFailureRelease)} ] || [ -f ${JSON.stringify(activationGatePath)} ] || exit 24; ` : ""}printf 'activate:%s\\n' "$ROLLBRIDGE_RELEASE_ID" >> ${JSON.stringify(lifecycleLogPath)}${options.handoffServiceActivateAmbiguousFailure ? `; [ "$ROLLBRIDGE_RELEASE_ID" != ${JSON.stringify(activationFailureRelease)} ] || [ -f ${JSON.stringify(activationGatePath)} ] || exit 24` : ""}`,
       quietCommand: `${options.handoffServiceQuietFailure ? `[ -f ${JSON.stringify(retirementGatePath)} ] || exit 23; ` : ""}printf 'retire:%s\\n' "$ROLLBRIDGE_RELEASE_ID" >> ${JSON.stringify(lifecycleLogPath)}`
     } : options.handoffServiceQuiet || options.handoffServiceQuietFailure ? {
       quietCommand: options.handoffServiceQuietFailure ? "exit 23" : `printf '%s\\n' "$ROLLBRIDGE_RELEASE_ID" >> ${JSON.stringify(serviceQuietPath)}`
@@ -1713,6 +1938,10 @@ async function createFixture(options = {}) {
     processes.push({
       command: `${JSON.stringify(process.execPath)} -e ${JSON.stringify(`process.on('SIGTERM', () => setTimeout(() => process.exit(0), ${options.workerStopDelayMs || 0})); setInterval(() => {}, 1000)`)}`,
       id: "worker",
+      ...(options.workerReactivationLifecycle ? {lifecycle: {
+        quietCommand: `printf 'worker-retire:%s\\n' "$ROLLBRIDGE_RELEASE_ID" >> ${JSON.stringify(lifecycleLogPath)}`,
+        reactivateCommand: `${options.workerReactivationFailure ? "exit 25; " : ""}printf 'worker-reactivate:%s\\n' "$ROLLBRIDGE_RELEASE_ID" >> ${JSON.stringify(lifecycleLogPath)}`
+      }} : {}),
       nonBlockingDrain: true,
       policy: "companion"
     })