rollbridge 0.1.40 → 0.1.42

package/README.md

@@ -89,6 +89,7 @@ export default {
       command: "env VELOCIOUS_BACKGROUND_JOBS_PORT={{port}} npx velocious background-jobs-main",
       lifecycle: {
         activateCommand: 'npx velocious background-jobs:activate --generation "$ROLLBRIDGE_RELEASE_ID" --socket "$VELOCIOUS_BACKGROUND_JOBS_LIFECYCLE_SOCKET"',
+        activateTimeoutMs: 60000,
         quietCommand: 'npx velocious background-jobs:retire --generation "$ROLLBRIDGE_RELEASE_ID" --socket "$VELOCIOUS_BACKGROUND_JOBS_LIFECYCLE_SOCKET"'
       },
       port: {from: 7331, to: 7399}
@@ -188,7 +189,8 @@ 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
+activation command before reporting it running. Set `activateTimeoutMs` when the
+activation acknowledgement can exceed its 30-second default. Omit `activateCommand` to
 preserve the existing hook-free ordering.
 
 See [`docs/workers.md`](docs/workers.md) for the full release-generation

package/docs/config.md

@@ -303,8 +303,8 @@ service when the service starts as a quiescent candidate and requires an explici
 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
+proxy target synchronously. Activation is bounded by `lifecycle.activateTimeoutMs`,
+which defaults 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`.
 
@@ -347,7 +347,8 @@ legitimate hours-long generation drains are valid.
 
 | Field | Type | Default | Description |
 | --- | --- | --- | --- |
-| `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.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 by `activateTimeoutMs`. |
+| `lifecycle.activateTimeoutMs` | positive number | `30000` | Bounds activation, reactivation, and active-role restoration commands. |
 | `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). |

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.42",
   "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, activateTimeoutMs?: number, 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
@@ -343,20 +343,29 @@ function normalizeMemory(value, key, issues) {
  * @returns {LifecycleConfig} Normalized lifecycle hooks (no commands and a 0 drain by default).
  */
 function normalizeLifecycle(value, key, issues) {
-  if (value === undefined || value === null) return {drainTimeoutMs: 0}
+  if (value === undefined || value === null) return {activateTimeoutMs: 30000, 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}
+    return {activateTimeoutMs: 30000, drainTimeoutMs: 0}
   }
 
+  const activateTimeoutMs = normalizeNumber(value.activateTimeoutMs, `${key}.activateTimeoutMs`, issues, {default: 30000})
   const drainTimeoutMs = normalizeNumber(value.drainTimeoutMs, `${key}.drainTimeoutMs`, issues, {default: 0})
   /** @type {LifecycleConfig} */
-  const lifecycle = {drainTimeoutMs: nonNegativeOrDefault(drainTimeoutMs, `${key}.drainTimeoutMs`, issues, 0, false)}
+  const lifecycle = {
+    activateTimeoutMs: activateTimeoutMs > 0 ? activateTimeoutMs : 30000,
+    drainTimeoutMs: nonNegativeOrDefault(drainTimeoutMs, `${key}.drainTimeoutMs`, issues, 0, false)
+  }
+
+  if (activateTimeoutMs <= 0) {
+    issues.push({fix: `Set ${key}.activateTimeoutMs to a positive number of milliseconds, e.g. 30000.`, message: `${key}.activateTimeoutMs must be a positive number`})
+  }
 
   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 +385,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 +400,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

@@ -4,7 +4,7 @@ import {EventEmitter} from "node:events"
 import {spawn} from "node:child_process"
 import {processGroupHasLiveMembers, processGroupMembers} from "./process-memory.js"
 
-const ACTIVATION_HOOK_TIMEOUT_MS = 30000
+const DEFAULT_ACTIVATION_HOOK_TIMEOUT_MS = 30000
 const MAX_BUFFERED_OUTPUT_CHARACTERS = 64 * 1024
 
 /**
@@ -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,13 +521,65 @@ 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`)
-    const error = await this.runHook(command, ACTIVATION_HOOK_TIMEOUT_MS, "activate command", pid)
-
-    if (error) throw error
+    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, this.activationHookTimeoutMs(), "activate command", pid)
+
+    if (error) throw error
+  }
+
+  /**
+   * 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, this.activationHookTimeoutMs(), 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)
+  }
+
   /**
    * Records the durable desired role without firing a lifecycle command.
    * @param {LifecycleRole} role - Exact role owned by this process generation.
@@ -538,16 +590,24 @@ 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 timeoutMs = this.lifecycleRole === "active" ? this.activationHookTimeoutMs() : this.hookTimeoutMs()
+    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
   }
 
+  /** @returns {number} Timeout used for activation/reactivation hooks. */
+  activationHookTimeoutMs() {
+    return this.lifecycle.activateTimeoutMs ?? DEFAULT_ACTIVATION_HOOK_TIMEOUT_MS
+  }
+
   /** @returns {number} Timeout used for lifecycle hooks. */
   hookTimeoutMs() {
     if (this.stopTimeoutMs === "indefinite") return 30000
@@ -760,7 +820,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,