rollbridge 0.1.28 → 0.1.30

package/docs/velocious.md

@@ -26,6 +26,7 @@ export default {
   application: "tensorbuzz",
   control: {path: "/tmp/rollbridge-tensorbuzz.sock"},
   statePath: "/var/lib/rollbridge/tensorbuzz.json",
+  ownerRecovery: {reconnectGraceMs: 30000},
 
   proxy: {
     host: "127.0.0.1",
@@ -56,6 +57,7 @@ export default {
         VELOCIOUS_BACKGROUND_JOBS_PORT: "{{port}}"
       },
       command: "wait-for-it 127.0.0.1:{{ports.beacon}} --strict -- npx velocious background-jobs-main",
+      lifecycle: {quietCommand: "appctl jobs-main-retire --pid $ROLLBRIDGE_PID"},
       port: {from: 7331, to: 7399}
     },
     {
@@ -89,6 +91,9 @@ export default {
 }
 ```
 
+`appctl` is a placeholder for a reviewed Velocious/application integration that
+quiesces jobs-main admission without terminating its worker/report endpoint.
+
 Beacon keeps its fixed port because it is intentionally shared. Jobs-main uses a
 range because every release gets its own coordinator. Same-release
 `{{ports.background-jobs-main}}` expansion ensures that old workers retain the
@@ -138,10 +143,12 @@ report every referenced release directory so Rampway can pin it against cleanup.
 A runtime owner/version handoff preserves or transfers that supervision and
 returns after the replacement is healthy; it is not a full synchronous shutdown.
 
-These are target requirements. Current Rollbridge drains releases
-asynchronously only while the same daemon remains alive, cannot re-adopt
-surviving PIDs after restart, and stops rather than transfers all managed
-processes during `--takeover-owner`; see [`docs/cli.md`](cli.md#daemon).
+Rollbridge implements post-activation quiescence, concurrent endpoints,
+asynchronous generation drain, and `status.releaseReferences`. With
+`ownerRecovery`, a same-authority replacement reconnects to the guardian rather
+than adopting arbitrary PIDs, and `ensure-daemon` can atomically transfer
+incompatible owner/config/control-socket/package/runtime authority while the
+guardian retains every generation. `--takeover-owner` is not this handoff.
 
 ## Timeouts
 

package/docs/workers.md

@@ -17,6 +17,7 @@ fixed port such as `7330`.
   policy: "service",
   deployStrategy: "handoff",
   command: "npx velocious background-jobs-main",
+  lifecycle: {quietCommand: "appctl jobs-main-retire --pid $ROLLBRIDGE_PID"},
   port: {from: 7331, to: 7399}
 },
 {
@@ -30,6 +31,9 @@ fixed port such as `7330`.
 }
 ```
 
+The illustrative `appctl` command must be replaced by the application's real,
+reviewed jobs-main quiescence control.
+
 Each worker receives its generation's jobs-main port. Old workers keep that port
 for their entire lifetime; normal deploy draining never hands them to, or lets
 them reconnect to, the new jobs-main. `replicas` scales the pool as
@@ -67,8 +71,10 @@ HTTP/WebSocket connections, or other retained services to finish. The required
 supervisor contract durably retains generations after the command returns and
 across later deploys and supervisor/host recovery. Every referenced release
 directory must be reported to Rampway and stays pinned against cleanup until the
-last retained process exits. Current Rollbridge provides asynchronous draining
-only for the lifetime of the current daemon; see the current-behavior notes in
+last retained process exits. Rollbridge exposes references as
+`status.releaseReferences`, supports concurrent retired generations, and with
+`ownerRecovery` preserves them across same-authority daemon recovery and atomic
+incompatible `ensure-daemon` owner replacement; see
 [`docs/config.md`](config.md#processesdeploystrategy) and
 [`docs/cli.md`](cli.md#deploy).
 

package/examples/tensorbuzz.com.js

@@ -2,8 +2,9 @@
 //
 // Nginx should keep proxying the backend host to 127.0.0.1:4500. Rollbridge
 // binds that stable HTTP port, forwards to the active release's internal web
-// port, keeps Beacon/jobs-main as daemon-wide services, and starts one
-// background worker per active release.
+// port and keeps Beacon daemon-wide. The jobs-main and worker controls below
+// are illustrative: replace appctl with application commands that quiesce new
+// admission without terminating the generation.
 
 export default {
   application: "tensorbuzz",
@@ -12,6 +13,9 @@ export default {
     path: "/tmp/rollbridge-tensorbuzz.sock"
   },
 
+  statePath: "/var/lib/rollbridge/tensorbuzz.json",
+  ownerRecovery: {reconnectGraceMs: 30000},
+
   proxy: {
     host: "127.0.0.1",
     port: 4500,
@@ -37,6 +41,7 @@ export default {
     {
       id: "background-jobs-main",
       policy: "service",
+      deployStrategy: "handoff",
       cwd: "{{releasePath}}/backend",
       env: {
         NODE_ENV: "production",
@@ -45,7 +50,8 @@ export default {
         VELOCIOUS_BACKGROUND_JOBS_PORT: "{{port}}"
       },
       command: "wait-for-it 127.0.0.1:{{ports.beacon}} --strict -- npx velocious background-jobs-main",
-      port: 7331
+      lifecycle: {quietCommand: "appctl jobs-main-retire --pid $ROLLBRIDGE_PID"},
+      port: {from: 7331, to: 7399}
     },
     {
       id: "background-jobs-worker",
@@ -58,7 +64,9 @@ export default {
         VELOCIOUS_BACKGROUND_JOBS_PORT: "{{ports.background-jobs-main}}"
       },
       command: "wait-for-it 127.0.0.1:{{ports.beacon}} --strict -- wait-for-it 127.0.0.1:{{ports.background-jobs-main}} --strict -- npx velocious background-jobs-worker",
-      gracefulStopMs: 60000
+      lifecycle: {quietCommand: "appctl jobs-worker-retire --pid $ROLLBRIDGE_PID"},
+      nonBlockingDrain: true,
+      gracefulStopMs: "indefinite"
     },
     {
       id: "web",

package/package.json

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

package/src/cli.js

@@ -5,17 +5,20 @@ import fsPromises from "node:fs/promises"
 import {createHash} from "node:crypto"
 import path from "node:path"
 import {spawn} from "node:child_process"
-import {Command} from "commander"
-import RollbridgeDaemon from "./daemon.js"
+import {Command, Option} from "commander"
+import RollbridgeDaemon, {ownerConfigDigest} from "./daemon.js"
 import {loadDaemonRuntimeIdentity, prepareDaemonRuntime} from "./daemon-runtime.js"
 import {loadConfig, parseConfigFile, resolveConfigPath, validateConfig} from "./config.js"
 import {runEnvironmentChecks, runReleaseChecks} from "./doctor.js"
 import {predeployCleanup} from "./predeploy-cleanup.js"
 import {recoverOrphans} from "./recover.js"
 import {sendControlCommand} from "./control-client.js"
+import {readState} from "./state-store.js"
 
 const DEFAULT_DAEMON_START_TIMEOUT_MS = 10000
 
+/** @typedef {import("node:child_process").ChildProcess["signalCode"]} DaemonExitSignal */
+
 /**
  * Runs the CLI.
  * @param {string[]} argv - Process argv.
@@ -37,16 +40,45 @@ export async function runCli(argv) {
     .option("--revision <sha>", "Bootstrap revision (requires --config, --release-path, and --release-id)")
     .option("--boot-attestation <digest>", "Opaque bootstrap ownership attestation (requires the complete bootstrap release tuple)")
     .option("--takeover-owner", "Boot and health-check before retiring the current external owner")
+    .option("--replace-owner", "Resume a prepared durable owner replacement")
+    .addOption(new Option("--legacy-incumbent-pid <pid>").hideHelp())
     .action(async (options) => {
       const bootstrap = await validateDaemonBootstrapOptions(options)
       const configPath = await resolveConfigPath(options.config)
       const config = await loadConfig(configPath)
       const runtime = await loadDaemonRuntimeIdentity(process.env.ROLLBRIDGE_DAEMON_RUNTIME_MANIFEST)
-      const daemon = new RollbridgeDaemon({bootstrap, config, configPath, runtime})
+      const daemon = new RollbridgeDaemon({
+        bootstrap,
+        config,
+        configPath,
+        legacyIncumbentPid: positiveIntegerOrUndefined(options.legacyIncumbentPid, "legacy incumbent pid"),
+        runtime
+      })
 
       if (options.takeoverOwner && (!bootstrap || !bootstrap.attestation)) throw new Error("Daemon --takeover-owner requires the complete bootstrap release tuple and --boot-attestation.")
 
-      if (!options.takeoverOwner) await daemon.start({exposeControl: !bootstrap})
+      if (options.replaceOwner) {
+        if (bootstrap || options.takeoverOwner) throw new Error("Daemon --replace-owner cannot be combined with bootstrap takeover options.")
+        await daemon.replaceIncompatibleOwner()
+      }
+
+      if (!options.takeoverOwner && !options.replaceOwner) {
+        try {
+          await daemon.start({exposeControl: !bootstrap})
+        } catch (error) {
+          if (!config.ownerRecovery) throw error
+
+          const winner = await sendControlCommand({command: {command: "status"}, path: config.control.path}).catch(() => undefined)
+          const matchingWinner = winner?.application === config.application &&
+            winner.ownerRecovery && typeof winner.ownerRecovery === "object" && !Array.isArray(winner.ownerRecovery) &&
+            winner.ownerRecovery.configDigest === daemon.ownerRecoveryConfigDigest() &&
+            ((!runtime && !winner.daemonRuntime) || (runtime && winner.daemonRuntime && typeof winner.daemonRuntime === "object" && !Array.isArray(winner.daemonRuntime) && winner.daemonRuntime.digest === runtime.digest))
+
+          if (!matchingWinner) throw error
+          await daemon.abandonOwnerRecoveryAttempt()
+          return
+        }
+      }
 
       const shutdown = async () => {
         await daemon.shutdown()
@@ -70,6 +102,11 @@ export async function runCli(argv) {
 
           daemon.logger("bootstrap activation failed", {releaseId: bootstrap.releaseId, status: "error", ...errorLogData(failure)})
 
+          if (config.ownerRecovery && daemon.activeRelease) {
+            await daemon.exposeControl()
+            return
+          }
+
           try {
             await daemon.shutdown()
           } catch (shutdownError) {
@@ -798,23 +835,56 @@ async function validateDaemonBootstrapOptions(options) {
 async function ensureDaemonRunning({config, configPath, logPath, pidPath, runtimePath, timeoutMs}) {
   const runtime = await prepareDaemonRuntime(runtimePath || defaultDaemonRuntimePath(config))
   const existingStatus = await daemonStatus(config)
+  const expectedConfigDigest = ownerConfigDigest(config)
 
   if (existingStatus) {
-    assertCompatibleDaemonRuntime(existingStatus, runtime)
-    return existingStatus
+    const matchingRecoveryAuthority = !config.ownerRecovery || (
+      existingStatus.ownerRecovery && typeof existingStatus.ownerRecovery === "object" && !Array.isArray(existingStatus.ownerRecovery) &&
+      existingStatus.ownerRecovery.configDigest === expectedConfigDigest
+    )
+
+    if (compatibleDaemonRuntime(existingStatus, runtime) && matchingRecoveryAuthority) return existingStatus
+    if (!config.ownerRecovery) assertCompatibleDaemonRuntime(existingStatus, runtime)
   }
 
-  await startDaemonProcess({
+  const persistedState = config.ownerRecovery && config.statePath ? await readState(config.statePath) : undefined
+  const persistedOwner = persistedState && typeof persistedState === "object" && !Array.isArray(persistedState) ? persistedState : undefined
+  const persistedRecovery = persistedOwner?.recovery
+  const replacement = Boolean(config.ownerRecovery && (existingStatus || (persistedRecovery && typeof persistedRecovery === "object" && !Array.isArray(persistedRecovery) && (
+    persistedRecovery.configDigest !== expectedConfigDigest || !compatibleDaemonRuntime(/** @type {Record<string, import("./json.js").JsonValue>} */ (persistedOwner), runtime)
+  ))))
+  const resolvedPidPath = pidPath || defaultDaemonPidPath(config)
+  const legacyIncumbentPid = replacement ? await readDaemonPid(resolvedPidPath) : undefined
+
+  await fsPromises.mkdir(path.dirname(resolvedPidPath), {recursive: true})
+  const candidate = await startDaemonProcess({
     configPath,
     logPath: logPath || defaultDaemonLogPath(config),
-    pidPath: pidPath || defaultDaemonPidPath(config),
+    replacement,
+    legacyIncumbentPid,
     runtime
   })
+  let startedStatus
 
-  const startedStatus = await waitForDaemonStatus(config, timeoutMs)
+  try {
+    startedStatus = await waitForDaemonStatus(config, timeoutMs, {
+      candidate,
+      configDigest: config.ownerRecovery ? expectedConfigDigest : undefined,
+      runtime
+    })
 
-  assertCompatibleDaemonRuntime(startedStatus, runtime)
-  return startedStatus
+    assertCompatibleDaemonRuntime(startedStatus, runtime)
+    const startedPid = positiveIntegerOrUndefined(
+      typeof startedStatus.daemonPid === "number" ? String(startedStatus.daemonPid) : undefined,
+      "started daemon status PID"
+    )
+
+    if (!startedPid) throw new Error("Started Rollbridge daemon did not report its exact PID")
+    await fsPromises.writeFile(resolvedPidPath, `${startedPid}\n`)
+    return startedStatus
+  } finally {
+    candidate.unref()
+  }
 }
 
 /**
@@ -843,60 +913,156 @@ async function daemonStatus(config) {
  * @param {object} args - Options.
  * @param {string} args.configPath - Config path.
  * @param {string} args.logPath - Log file path.
- * @param {string} args.pidPath - PID file path.
+ * @param {boolean} args.replacement - Whether to run the incompatible replacement transaction.
+ * @param {number | undefined} args.legacyIncumbentPid - Exact incumbent recorded before candidate spawn.
  * @param {import("./daemon-runtime.js").DaemonRuntimeIdentity} args.runtime - Prepared runtime.
- * @returns {Promise<void>} Resolves after the child has been spawned.
+ * @returns {Promise<import("node:child_process").ChildProcess>} Referenced child after exact spawn completion.
  */
-async function startDaemonProcess({configPath, logPath, pidPath, runtime}) {
+async function startDaemonProcess({configPath, legacyIncumbentPid, logPath, replacement = false, runtime}) {
   await fsPromises.mkdir(path.dirname(logPath), {recursive: true})
-  await fsPromises.mkdir(path.dirname(pidPath), {recursive: true})
 
   const stdoutFd = fs.openSync(logPath, "a")
   const stderrFd = fs.openSync(logPath, "a")
 
   try {
-    const child = spawn(process.execPath, [path.join(runtime.path, "bin", "rollbridge"), "daemon", "--config", configPath], {
+    const child = spawn(process.execPath, [
+      path.join(runtime.path, "bin", "rollbridge"), "daemon", "--config", configPath,
+      ...(replacement ? ["--replace-owner"] : []),
+      ...(legacyIncumbentPid ? ["--legacy-incumbent-pid", String(legacyIncumbentPid)] : [])
+    ], {
       detached: true,
       env: {...process.env, ROLLBRIDGE_DAEMON_RUNTIME_MANIFEST: path.join(runtime.path, "runtime.json")},
       stdio: ["ignore", stdoutFd, stderrFd]
     })
 
-    child.unref()
+    await new Promise((resolve, reject) => {
+      const onError = (/** @type {Error} */ error) => finish(error)
+      const onSpawn = () => finish(undefined)
+      const finish = (/** @type {Error | undefined} */ error) => {
+        child.off("error", onError)
+        child.off("spawn", onSpawn)
+        if (error) reject(error)
+        else resolve(undefined)
+      }
 
-    if (child.pid) {
-      await fsPromises.writeFile(pidPath, `${child.pid}\n`)
-    }
+      child.once("error", onError)
+      child.once("spawn", onSpawn)
+    })
+    return child
   } finally {
     fs.closeSync(stdoutFd)
     fs.closeSync(stderrFd)
   }
 }
 
+/**
+ * Reads an exact daemon PID before the candidate overwrites the PID file.
+ * @param {string} pidPath - Daemon PID file.
+ * @returns {Promise<number | undefined>} Positive PID when the file exists and is valid.
+ */
+async function readDaemonPid(pidPath) {
+  let value
+
+  try {
+    value = await fsPromises.readFile(pidPath, "utf8")
+  } catch (error) {
+    if (error && typeof error === "object" && "code" in error && error.code === "ENOENT") return undefined
+    throw error
+  }
+  const trimmed = value.trim()
+
+  if (!/^\d+$/.test(trimmed)) throw new Error(`Daemon PID file ${pidPath} does not contain one positive integer`)
+  return positiveIntegerOrUndefined(trimmed, `daemon PID file ${pidPath}`)
+}
+
+/**
+ * @param {string | undefined} value - Integer text.
+ * @param {string} label - Diagnostic label.
+ * @returns {number | undefined} Positive integer or undefined.
+ */
+function positiveIntegerOrUndefined(value, label) {
+  if (value === undefined) return undefined
+  const parsed = Number(value)
+
+  if (!Number.isSafeInteger(parsed) || parsed < 1) throw new Error(`${label} must be a positive integer`)
+  return parsed
+}
+
 /**
  * Waits until a daemon answers status commands.
  * @param {import("./config.js").RollbridgeConfig} config - Loaded config.
  * @param {number} timeoutMs - Timeout in milliseconds.
+ * @param {{candidate?: import("node:child_process").ChildProcess, configDigest?: string, runtime?: import("./daemon-runtime.js").DaemonRuntimeIdentity}} [expected] - Required authority and exact spawned candidate.
  * @returns {Promise<Record<string, import("./json.js").JsonValue>>} Daemon status response.
  */
-async function waitForDaemonStatus(config, timeoutMs) {
+async function waitForDaemonStatus(config, timeoutMs, expected = {}) {
   const deadline = Date.now() + timeoutMs
   let lastError = /** @type {Error | undefined} */ (undefined)
+  let candidateExit = expected.candidate && (expected.candidate.exitCode !== null || expected.candidate.signalCode !== null)
+    ? {code: expected.candidate.exitCode, signal: expected.candidate.signalCode}
+    : undefined
+  let wakeDelay = /** @type {(() => void) | undefined} */ (undefined)
+  const onCandidateExit = (/** @type {number | null} */ code, /** @type {DaemonExitSignal} */ signal) => {
+    candidateExit = {code, signal}
+    wakeDelay?.()
+  }
+
+  expected.candidate?.once("exit", onCandidateExit)
+
+  try {
+    while (Date.now() < deadline) {
+      let status
+
+      try {
+        status = await daemonStatus(config)
+      } catch (error) {
+        lastError = error instanceof Error ? error : new Error(String(error))
+      }
 
-  while (Date.now() < deadline) {
-    try {
-      const status = await daemonStatus(config)
+      if (status) {
+        const statusPid = typeof status.daemonPid === "number" ? status.daemonPid : undefined
+        const candidateResolved = !expected.candidate || candidateExit || statusPid === expected.candidate.pid
 
-      if (status) return status
-    } catch (error) {
-      lastError = error instanceof Error ? error : new Error(String(error))
+        if (expected.runtime && !compatibleDaemonRuntime(status, expected.runtime)) {
+          if (!expected.configDigest) assertCompatibleDaemonRuntime(status, expected.runtime)
+        } else if (candidateResolved && (!expected.configDigest || (status.ownerRecovery && typeof status.ownerRecovery === "object" && !Array.isArray(status.ownerRecovery) && status.ownerRecovery.configDigest === expected.configDigest))) {
+          return status
+        }
+      }
+
+      if (candidateExit && expected.candidate) throw candidateExitError(expected.candidate, candidateExit)
+      await new Promise((resolve) => {
+        const timer = setTimeout(finish, 100)
+        /** Completes one readiness interval or candidate-exit wake-up. */
+        function finish() {
+          clearTimeout(timer)
+          wakeDelay = undefined
+          resolve(undefined)
+        }
+
+        wakeDelay = finish
+      })
     }
 
-    await new Promise((resolve) => setTimeout(resolve, 100))
-  }
+    const detail = lastError ? ` Last error: ${lastError.message}` : ""
 
-  const detail = lastError ? ` Last error: ${lastError.message}` : ""
+    throw new Error(`Rollbridge daemon did not become ready within ${timeoutMs}ms.${detail}`)
+  } finally {
+    expected.candidate?.off("exit", onCandidateExit)
+    wakeDelay = undefined
+  }
+}
 
-  throw new Error(`Rollbridge daemon did not become ready within ${timeoutMs}ms.${detail}`)
+/**
+ * @param {import("node:child_process").ChildProcess} candidate - Exact spawned daemon candidate.
+ * @param {{code: number | null, signal: DaemonExitSignal}} exit - Exact exit status.
+ * @returns {Error} Actionable pre-readiness failure.
+ */
+function candidateExitError(candidate, exit) {
+  return new Error(
+    `Rollbridge daemon candidate ${candidate.pid ?? "unknown"} exited before readiness ` +
+    `(code ${exit.code ?? "none"}, signal ${exit.signal ?? "none"}). Spawned argv: ${JSON.stringify(candidate.spawnargs)}`
+  )
 }
 
 /**
@@ -933,11 +1099,7 @@ function defaultDaemonRuntimePath(config) {
  * @returns {void}
  */
 function assertCompatibleDaemonRuntime(status, expected) {
-  const runtime = status.daemonRuntime
-  const compatible = runtime && typeof runtime === "object" && !Array.isArray(runtime) &&
-    runtime.format === expected.format && runtime.version === expected.version && runtime.digest === expected.digest
-
-  if (compatible) return
+  if (compatibleDaemonRuntime(status, expected)) return
 
   throw new Error(
     "The running Rollbridge daemon has a legacy or mismatched runtime. " +
@@ -945,6 +1107,17 @@ function assertCompatibleDaemonRuntime(status, expected) {
   )
 }
 
+/**
+ * @param {Record<string, import("./json.js").JsonValue>} status - Daemon status.
+ * @param {import("./daemon-runtime.js").DaemonRuntimeIdentity} expected - Runtime.
+ * @returns {boolean} Whether the runtime authorities match.
+ */
+function compatibleDaemonRuntime(status, expected) {
+  const runtime = status.daemonRuntime
+
+  return Boolean(runtime && typeof runtime === "object" && !Array.isArray(runtime) && runtime.format === expected.format && runtime.version === expected.version && runtime.digest === expected.digest)
+}
+
 /**
  * @param {string | undefined} value - Raw timeout value.
  * @returns {number} Timeout in milliseconds.

package/src/config.js

@@ -23,7 +23,8 @@ import {pathToFileURL} from "node:url"
  * @typedef {{includes: string[], name: string}} LegacyTakeoverProcessConfig
  * @typedef {{forceStopTimeoutMs: number, processes: LegacyTakeoverProcessConfig[], screens: string[]}} LegacyTakeoverConfig
  * @typedef {{keep: number, maxAgeMs: number}} ReleaseRetentionConfig
- * @typedef {{application: string, control: ControlConfig, legacyTakeover?: LegacyTakeoverConfig, processes: ProcessConfig[], proxy: ProxyConfig, releaseRetention: ReleaseRetentionConfig, statePath?: string}} RollbridgeConfig
+ * @typedef {{reconnectGraceMs: number}} OwnerRecoveryConfig
+ * @typedef {{application: string, control: ControlConfig, legacyTakeover?: LegacyTakeoverConfig, ownerRecovery?: OwnerRecoveryConfig, processes: ProcessConfig[], proxy: ProxyConfig, releaseRetention: ReleaseRetentionConfig, statePath?: string}} RollbridgeConfig
  * @typedef {{fix: string, message: string}} ConfigIssue
  */
 
@@ -150,10 +151,15 @@ export function validateConfig(rawConfig, configPath = process.cwd()) {
   const legacyTakeover = normalizeLegacyTakeover(source.legacyTakeover, proxy, issues)
   const releaseRetention = normalizeReleaseRetention(objectAt(source.releaseRetention, "releaseRetention", issues, {}), issues)
   const statePath = source.statePath === undefined || source.statePath === null ? undefined : normalizeString(source.statePath, "statePath", issues)
+  const ownerRecoverySource = source.ownerRecovery === undefined || source.ownerRecovery === null ? undefined : objectAt(source.ownerRecovery, "ownerRecovery", issues)
+  const reconnectGraceMs = ownerRecoverySource ? normalizeNumber(ownerRecoverySource.reconnectGraceMs, "ownerRecovery.reconnectGraceMs", issues, {default: 30000}) : 30000
+  const ownerRecovery = ownerRecoverySource ? {reconnectGraceMs: nonNegativeOrDefault(reconnectGraceMs, "ownerRecovery.reconnectGraceMs", issues, 30000, true)} : undefined
+
+  if (ownerRecovery && !statePath) issues.push({fix: "Configure statePath when ownerRecovery is enabled.", message: "ownerRecovery requires statePath"})
 
   validateProcessSet(processes, issues)
 
-  return {config: {application, control, legacyTakeover, processes, proxy, releaseRetention, statePath}, issues}
+  return {config: {application, control, legacyTakeover, ownerRecovery, processes, proxy, releaseRetention, statePath}, issues}
 }
 
 /**

package/src/control-client.js

@@ -27,7 +27,15 @@ export async function sendControlCommand({command, path}) {
       if (newlineIndex < 0) return
 
       const line = buffer.slice(0, newlineIndex)
-      const response = JSON.parse(line)
+      let response
+
+      try {
+        response = JSON.parse(line)
+      } catch (error) {
+        socket.destroy()
+        reject(new Error(`Invalid Rollbridge control response from ${path}`, {cause: error}))
+        return
+      }
 
       socket.end()
 
@@ -40,3 +48,112 @@ export async function sendControlCommand({command, path}) {
     socket.write(`${JSON.stringify(command)}\n`)
   })
 }
+
+/**
+ * Opens one incumbent control connection that survives listener unlink during handoff.
+ * @param {string} path - Control socket path.
+ * @returns {Promise<ControlSession>} Connected session.
+ */
+export async function openControlSession(path) {
+  const session = new ControlSession(path)
+
+  await session.connect()
+  return session
+}
+
+class ControlSession {
+  /** @param {string} path - Control socket path. */
+  constructor(path) {
+    this.path = path
+    this.socket = /** @type {net.Socket | undefined} */ (undefined)
+    this.buffer = ""
+    this.pending = /** @type {{reject: (error: Error) => void, resolve: (value: Record<string, JsonValue>) => void} | undefined} */ (undefined)
+    this.eventHandlers = /** @type {((event: Record<string, JsonValue>) => void)[]} */ ([])
+    this.closePromise = /** @type {Promise<void> | undefined} */ (undefined)
+    this.resolveClose = /** @type {(() => void) | undefined} */ (undefined)
+  }
+
+  /** Connects before the incumbent stops accepting new control clients. */
+  async connect() {
+    const socket = net.createConnection(this.path)
+
+    socket.setEncoding("utf8")
+    await new Promise((resolve, reject) => {
+      socket.once("connect", resolve)
+      socket.once("error", reject)
+    })
+    socket.on("data", (chunk) => this.onData(String(chunk)))
+    this.closePromise = new Promise((resolve) => { this.resolveClose = () => resolve(undefined) })
+    socket.once("close", () => {
+      this.pending?.reject(new Error(`Rollbridge control connection ${this.path} closed before its response`))
+      this.pending = undefined
+      this.resolveClose?.()
+    })
+    this.socket = socket
+  }
+
+  /**
+   * @param {Record<string, JsonValue>} command - Command payload.
+   * @returns {Promise<Record<string, JsonValue>>} Response payload.
+   */
+  async request(command) {
+    if (!this.socket || this.socket.destroyed) throw new Error(`Rollbridge control connection ${this.path} is not connected`)
+    if (this.pending) throw new Error("Rollbridge control session permits one in-flight command")
+    const response = new Promise((resolve, reject) => { this.pending = {reject, resolve} })
+
+    this.socket.write(`${JSON.stringify(command)}\n`)
+    return await response
+  }
+
+  /** Closes the persistent handoff connection. */
+  close() {
+    this.socket?.destroy()
+  }
+
+  /** Waits for the kernel to close the incumbent control connection. */
+  async closed() {
+    if (!this.closePromise) throw new Error(`Rollbridge control connection ${this.path} was not opened`)
+    await this.closePromise
+  }
+
+  /**
+   * Subscribes to authenticated incumbent handoff events.
+   * @param {(event: Record<string, JsonValue>) => void} handler - Event handler.
+   */
+  onEvent(handler) {
+    this.eventHandlers.push(handler)
+  }
+
+  /** @param {string} chunk - Protocol bytes. */
+  onData(chunk) {
+    this.buffer += chunk
+    let newlineIndex = this.buffer.indexOf("\n")
+
+    while (newlineIndex >= 0) {
+      const line = this.buffer.slice(0, newlineIndex)
+      this.buffer = this.buffer.slice(newlineIndex + 1)
+
+      try {
+        const response = JSON.parse(line)
+
+        if (response.event) {
+          for (const handler of this.eventHandlers) handler(response)
+        } else {
+          const pending = this.pending
+
+          this.pending = undefined
+          if (pending) {
+            if (response.status === "error") pending.reject(new Error(String(response.error || "Unknown Rollbridge error")))
+            else pending.resolve(response)
+          }
+        }
+      } catch (error) {
+        const pending = this.pending
+
+        this.pending = undefined
+        pending?.reject(new Error(`Invalid Rollbridge control response from ${this.path}`, {cause: error}))
+      }
+      newlineIndex = this.buffer.indexOf("\n")
+    }
+  }
+}