rollbridge 0.1.13 → 0.1.15

package/README.md

@@ -409,11 +409,12 @@ rollbridge daemon --config /srv/ticket-server/rollbridge.js \
 ```
 
 The four bootstrap inputs are all-or-nothing and use absolute config/release
-paths. Rollbridge binds its proxy and control listeners, activates the release
-through the normal deploy path, and stays foreground. A failed activation stops
-only processes started by that attempt and exits non-zero; persisted processes
-from a previous daemon are reported as orphans and are never recovered or killed
-implicitly; their live PID records remain in `statePath` for explicit recovery.
+paths. Rollbridge binds its proxy, activates the release through the normal
+deploy path, then exposes the control socket and stays foreground. A failed
+activation stops only processes started by that attempt and exits non-zero;
+persisted processes from a previous daemon are reported as orphans and are never
+recovered or killed implicitly; their live PID records remain in `statePath` for
+explicit recovery.
 
 Start the daemon only when it is not already running:
 

package/compose.yml

@@ -0,0 +1,17 @@
+# Canonical Rollbridge development service.
+name: rollbridge
+
+services:
+  dev:
+    image: threadwire-dev:local
+    entrypoint: ["/bin/sh", "-c"]
+    init: true
+    user: "1000:1000"
+    working_dir: /home/dev/rollbridge
+    environment:
+      GH_CONFIG_DIR: /home/dev/.config/gh
+      HOME: /home/dev
+    volumes:
+      - ${DEV_HOME_PATH:-/home/dev}:/home/dev
+      - ${GH_CONFIG_SOURCE_PATH:?Set GH_CONFIG_SOURCE_PATH in .env}:/home/dev/.config/gh:ro
+    command: ["exec sleep infinity"]

package/docs/cli.md

@@ -35,11 +35,12 @@ such as systemd (see `examples/rollbridge.service`).
 
 For boot/crash recovery, pass an explicit absolute `--config` and all three
 release options together. Rollbridge validates every bootstrap input before it
-binds listeners or starts processes, then binds the listeners and activates that
-exact release through the same deploy path used by the control socket: services,
+binds listeners or starts processes, then binds the proxy and activates that
+exact release through the normal deploy path: services,
 companions, the proxied process and health check, traffic switching, singletons,
-and service-template refresh. It then remains in the foreground with the normal
-signal behavior.
+and service-template refresh. Only after activation succeeds does it expose the
+control socket, preventing another deployment from overlapping bootstrap. It
+then remains in the foreground with the normal signal behavior.
 
 Bootstrap paths must be absolute and normalized, the release path must be an
 accessible directory, and release id/revision values accept letters, numbers,
@@ -47,10 +48,10 @@ dots, underscores, and hyphens (maximum 200 characters, beginning with a letter
 or number). Supplying only some bootstrap options, or an invalid value, exits
 non-zero before listeners start. Activation failure emits a structured
 `bootstrap activation failed` event, cleans up processes owned by that attempt,
-and exits non-zero without inventing an active release. `statePath` entries from
-a previous daemon remain advisory orphans: bootstrap never runs recovery and
-never signals those processes, and retains their live PID records in `statePath`
-for explicit recovery.
+and exits non-zero without exposing the control socket or inventing an active
+release. `statePath` entries from a previous daemon remain advisory orphans:
+bootstrap never runs recovery and never signals those processes, and retains
+their live PID records in `statePath` for explicit recovery.
 
 With no release options, daemon behavior is unchanged: it starts listener-only
 and waits for control-socket deployments.
@@ -61,6 +62,7 @@ and waits for control-socket deployments.
 rollbridge ensure-daemon [--config <path>]
                          [--daemon-log-path <path>]
                          [--daemon-pid-path <path>]
+                         [--daemon-runtime-path <path>]
                          [--daemon-start-timeout-ms <ms>]
 ```
 
@@ -68,11 +70,24 @@ Starts the daemon as a detached process **only if** the control socket is not
 already accepting commands, waits until it responds, then prints the daemon
 status JSON. Idempotent — safe to call before every deploy.
 
+Before starting a detached daemon, Rollbridge atomically copies its runtime code
+and production dependency closure into a content-addressed directory outside
+the invoking release. This keeps the long-lived daemon valid when deploy
+retention removes that release. A responsive daemon is reused only when its
+runtime identity matches the invoking Rollbridge installation; a legacy or
+mismatched daemon causes the command to fail before any deploy is sent. Stop and
+restart such a daemon explicitly during a safe maintenance handoff.
+
 - `--daemon-log-path <path>` — file the detached daemon's stdout/stderr is
   appended to. Default: `/tmp/rollbridge-<application>.log`. See
   [`logging.md`](logging.md) for the log format and rotation guidance.
 - `--daemon-pid-path <path>` — file the detached daemon's PID is written to.
   Default: `/tmp/rollbridge-<application>.pid`.
+- `--daemon-runtime-path <path>` — parent directory for content-addressed daemon
+  runtime snapshots. Default:
+  `/tmp/rollbridge-<user-id>-<application-hash>-runtime`. The directory must be owned
+  by the current user and must not be group/world writable; preparation or
+  validation failure aborts before daemon startup or deploy handoff.
 - `--daemon-start-timeout-ms <ms>` — how long to wait for the daemon to accept
   control commands before failing. Default: `10000`.
 
@@ -86,6 +101,7 @@ rollbridge deploy --release-path <path>
                   [--ensure-daemon]
                   [--daemon-log-path <path>]
                   [--daemon-pid-path <path>]
+                  [--daemon-runtime-path <path>]
                   [--daemon-start-timeout-ms <ms>]
 ```
 
@@ -154,6 +170,10 @@ Memory-supervised processes also report `rssBytes`, `memoryRestarts`,
 `lastMemoryRestartAt`, and `children` (the process tree: each group member's
 `pid`, `command`, and `rssBytes`).
 
+`daemonRuntime` identifies the immutable Rollbridge runtime serving the proxy:
+its runtime `format`, package `version`, content `digest`, and absolute `path`.
+`ensure-daemon` uses this attestation before reusing a responsive daemon.
+
 When [`statePath`](config.md#statepath) is configured, status also includes an
 `orphans` array: managed processes from a **previous** daemon that are still
 alive (`id`, `pid`, `releaseId`) — for example after the daemon restarted but its

package/docs/troubleshooting.md

@@ -1,5 +1,23 @@
 # Troubleshooting
 
+## Legacy or mismatched daemon runtime
+
+**Symptom.** `deploy --ensure-daemon` or `ensure-daemon` reports that the
+running daemon has a legacy or mismatched runtime and confirms that the deploy
+was not sent.
+
+**Cause.** A daemon already owns the stable proxy/control socket, but it cannot
+attest to the same immutable Rollbridge runtime as the CLI preparing the deploy.
+Rollbridge does not silently restart it because rebinding the proxy could cause
+downtime or abandon managed processes.
+
+**Fix.** Keep the current release active, explicitly stop and restart the daemon
+with the intended Rollbridge installation during a safe handoff, then retry the
+deploy. If durable runtime preparation itself fails, check permissions for
+`--daemon-runtime-path` (default
+`/tmp/rollbridge-<user-id>-<application-hash>-runtime`) before retrying. The directory
+must be private to the invoking user.
+
 Start with these three commands — they diagnose most problems without guessing:
 
 - `rollbridge validate` — config errors, with an example fix for each.

package/package.json

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

package/src/cli.js

@@ -2,10 +2,12 @@
 
 import fs from "node:fs"
 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 {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"
@@ -37,9 +39,10 @@ export async function runCli(argv) {
       const bootstrap = await validateDaemonBootstrapOptions(options)
       const configPath = await resolveConfigPath(options.config)
       const config = await loadConfig(configPath)
-      const daemon = new RollbridgeDaemon({config, configPath})
+      const runtime = await loadDaemonRuntimeIdentity(process.env.ROLLBRIDGE_DAEMON_RUNTIME_MANIFEST)
+      const daemon = new RollbridgeDaemon({config, configPath, runtime})
 
-      await daemon.start()
+      await daemon.start({exposeControl: !bootstrap})
 
       const shutdown = async () => {
         await daemon.shutdown()
@@ -52,6 +55,7 @@ export async function runCli(argv) {
       if (bootstrap) {
         try {
           await daemon.deploy(bootstrap)
+          await daemon.exposeControl()
         } catch {
           daemon.logger("bootstrap activation failed", {releaseId: bootstrap.releaseId, status: "error"})
           await daemon.shutdown()
@@ -70,6 +74,7 @@ export async function runCli(argv) {
     .option("--ensure-daemon", "Start the Rollbridge daemon if it is not already running")
     .option("--daemon-log-path <path>", "Log path used when --ensure-daemon starts the daemon")
     .option("--daemon-pid-path <path>", "PID file path used when --ensure-daemon starts the daemon")
+    .option("--daemon-runtime-path <path>", "Directory for durable daemon runtime snapshots")
     .option("--daemon-start-timeout-ms <ms>", "How long to wait for an ensured daemon to accept control commands")
     .action(async (options) => {
       const configPath = await resolveConfigPath(options.config)
@@ -77,11 +82,11 @@ export async function runCli(argv) {
 
       if (options.ensureDaemon) {
         await ensureDaemonRunning({
-          argv,
           config,
           configPath,
           logPath: options.daemonLogPath,
           pidPath: options.daemonPidPath,
+          runtimePath: options.daemonRuntimePath,
           timeoutMs: normalizeTimeoutMs(options.daemonStartTimeoutMs)
         })
       }
@@ -124,16 +129,17 @@ export async function runCli(argv) {
     .option("-c, --config <path>", "Config file path (defaults to rollbridge.js)")
     .option("--daemon-log-path <path>", "Daemon log path")
     .option("--daemon-pid-path <path>", "Daemon PID file path")
+    .option("--daemon-runtime-path <path>", "Directory for durable daemon runtime snapshots")
     .option("--daemon-start-timeout-ms <ms>", "How long to wait for the daemon to accept control commands")
     .action(async (options) => {
       const configPath = await resolveConfigPath(options.config)
       const config = await loadConfig(configPath)
       const response = await ensureDaemonRunning({
-        argv,
         config,
         configPath,
         logPath: options.daemonLogPath,
         pidPath: options.daemonPidPath,
+        runtimePath: options.daemonRuntimePath,
         timeoutMs: normalizeTimeoutMs(options.daemonStartTimeoutMs)
       })
 
@@ -757,27 +763,34 @@ async function validateDaemonBootstrapOptions(options) {
 /**
  * Starts a daemon when needed and waits until it accepts status commands.
  * @param {object} args - Options.
- * @param {string[]} args.argv - Original CLI argv.
  * @param {import("./config.js").RollbridgeConfig} args.config - Loaded config.
  * @param {string} args.configPath - Config path.
  * @param {string | undefined} args.logPath - Optional daemon log path.
  * @param {string | undefined} args.pidPath - Optional daemon PID path.
+ * @param {string | undefined} args.runtimePath - Optional durable runtime directory.
  * @param {number} args.timeoutMs - Startup timeout.
  * @returns {Promise<Record<string, import("./json.js").JsonValue>>} Daemon status response.
  */
-async function ensureDaemonRunning({argv, config, configPath, logPath, pidPath, timeoutMs}) {
+async function ensureDaemonRunning({config, configPath, logPath, pidPath, runtimePath, timeoutMs}) {
+  const runtime = await prepareDaemonRuntime(runtimePath || defaultDaemonRuntimePath(config))
   const existingStatus = await daemonStatus(config)
 
-  if (existingStatus) return existingStatus
+  if (existingStatus) {
+    assertCompatibleDaemonRuntime(existingStatus, runtime)
+    return existingStatus
+  }
 
   await startDaemonProcess({
-    argv,
     configPath,
     logPath: logPath || defaultDaemonLogPath(config),
-    pidPath: pidPath || defaultDaemonPidPath(config)
+    pidPath: pidPath || defaultDaemonPidPath(config),
+    runtime
   })
 
-  return await waitForDaemonStatus(config, timeoutMs)
+  const startedStatus = await waitForDaemonStatus(config, timeoutMs)
+
+  assertCompatibleDaemonRuntime(startedStatus, runtime)
+  return startedStatus
 }
 
 /**
@@ -804,17 +817,13 @@ async function daemonStatus(config) {
 /**
  * Starts the foreground daemon command as a detached child.
  * @param {object} args - Options.
- * @param {string[]} args.argv - Original CLI argv.
  * @param {string} args.configPath - Config path.
  * @param {string} args.logPath - Log file path.
  * @param {string} args.pidPath - PID file path.
+ * @param {import("./daemon-runtime.js").DaemonRuntimeIdentity} args.runtime - Prepared runtime.
  * @returns {Promise<void>} Resolves after the child has been spawned.
  */
-async function startDaemonProcess({argv, configPath, logPath, pidPath}) {
-  const binPath = argv[1] || process.argv[1]
-
-  if (!binPath) throw new Error("Unable to determine Rollbridge CLI path for daemon startup")
-
+async function startDaemonProcess({configPath, logPath, pidPath, runtime}) {
   await fsPromises.mkdir(path.dirname(logPath), {recursive: true})
   await fsPromises.mkdir(path.dirname(pidPath), {recursive: true})
 
@@ -822,9 +831,9 @@ async function startDaemonProcess({argv, configPath, logPath, pidPath}) {
   const stderrFd = fs.openSync(logPath, "a")
 
   try {
-    const child = spawn(process.execPath, [binPath, "daemon", "--config", configPath], {
+    const child = spawn(process.execPath, [path.join(runtime.path, "bin", "rollbridge"), "daemon", "--config", configPath], {
       detached: true,
-      env: process.env,
+      env: {...process.env, ROLLBRIDGE_DAEMON_RUNTIME_MANIFEST: path.join(runtime.path, "runtime.json")},
       stdio: ["ignore", stdoutFd, stderrFd]
     })
 
@@ -882,6 +891,36 @@ function defaultDaemonPidPath(config) {
   return `/tmp/rollbridge-${config.application}.pid`
 }
 
+/**
+ * @param {import("./config.js").RollbridgeConfig} config - Loaded config.
+ * @returns {string} Default durable daemon runtime directory.
+ */
+function defaultDaemonRuntimePath(config) {
+  const userId = typeof process.getuid === "function" ? process.getuid() : "user"
+  const applicationHash = createHash("sha256").update(config.application).digest("hex").slice(0, 16)
+
+  return `/tmp/rollbridge-${userId}-${applicationHash}-runtime`
+}
+
+/**
+ * Refuses to hand a deploy to a daemon whose immutable runtime does not match this CLI.
+ * @param {Record<string, import("./json.js").JsonValue>} status - Existing daemon status.
+ * @param {import("./daemon-runtime.js").DaemonRuntimeIdentity} expected - Expected runtime.
+ * @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
+
+  throw new Error(
+    "The running Rollbridge daemon has a legacy or mismatched runtime. " +
+    "The deploy was not sent. Keep the current release active, then explicitly stop and restart the daemon with this Rollbridge installation before retrying."
+  )
+}
+
 /**
  * @param {string | undefined} value - Raw timeout value.
  * @returns {number} Timeout in milliseconds.

package/src/daemon-runtime.js

@@ -0,0 +1,316 @@
+// @ts-check
+
+import {createHash} from "node:crypto"
+import {execFile} from "node:child_process"
+import fs from "node:fs/promises"
+import {createRequire} from "node:module"
+import os from "node:os"
+import path from "node:path"
+import {promisify} from "node:util"
+import {fileURLToPath} from "node:url"
+
+const RUNTIME_FORMAT = 1
+const execFileAsync = promisify(execFile)
+const packageRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..")
+
+/**
+ * @typedef {{digest: string, format: number, path: string, version: string}} DaemonRuntimeIdentity
+ */
+
+/**
+ * Atomically prepares a content-addressed Rollbridge runtime outside the package tree.
+ * @param {string} basePath - Stable parent directory for runtime snapshots.
+ * @returns {Promise<DaemonRuntimeIdentity>} Prepared runtime identity.
+ */
+export async function prepareDaemonRuntime(basePath) {
+  await fs.mkdir(basePath, {mode: 0o700, recursive: true})
+  await validateRuntimeBase(basePath)
+
+  const stagingPath = await fs.mkdtemp(path.join(basePath, ".prepare-"))
+
+  try {
+    await copyPackageClosure(packageRoot, stagingPath, new Set(), true)
+    const digest = await directoryDigest(stagingPath)
+    const version = await packageVersion(stagingPath)
+    const runtimePath = path.join(basePath, digest)
+    const identity = {digest, format: RUNTIME_FORMAT, path: runtimePath, version}
+
+    await fs.writeFile(path.join(stagingPath, "runtime.json"), `${JSON.stringify(identity, null, 2)}\n`, {mode: 0o600})
+    await validateRuntime(stagingPath, identity)
+
+    try {
+      await fs.rename(stagingPath, runtimePath)
+    } catch (error) {
+      const fileError = /** @type {Error & {code?: string}} */ (error)
+
+      if (!hasCode(fileError, "EEXIST") && !hasCode(fileError, "ENOTEMPTY")) throw error
+      await validateRuntime(runtimePath, identity)
+      await fs.rm(stagingPath, {force: true, recursive: true})
+    }
+
+    await validateRuntime(runtimePath, identity)
+    return identity
+  } catch (error) {
+    await fs.rm(stagingPath, {force: true, recursive: true}).catch(() => {})
+    throw error
+  }
+}
+
+/**
+ * Rejects a runtime path beneath any ancestor that another local user could replace.
+ * @param {string} basePath - Runtime parent directory.
+ * @returns {Promise<void>} Resolves when the full path is safely anchored.
+ */
+async function validateRuntimeBase(basePath) {
+  const absolutePath = path.resolve(basePath)
+  const rootPath = path.parse(absolutePath).root
+  const relativeParts = path.relative(rootPath, absolutePath).split(path.sep).filter(Boolean)
+  const paths = [rootPath]
+
+  for (const part of relativeParts) paths.push(path.join(paths.at(-1) || rootPath, part))
+
+  for (const candidatePath of paths) {
+    const stats = await fs.lstat(candidatePath)
+
+    if (!stats.isDirectory() || stats.isSymbolicLink()) {
+      throw new Error(`Every Rollbridge daemon runtime path component must be a real directory: ${candidatePath}`)
+    }
+
+    if (typeof process.getuid !== "function") continue
+
+    const ownedByTrustedUser = stats.uid === 0 || stats.uid === process.getuid()
+    const writableByOthers = (stats.mode & 0o022) !== 0
+    const sticky = (stats.mode & 0o1000) !== 0
+
+    if (candidatePath !== absolutePath && !ownedByTrustedUser) {
+      throw new Error(`Rollbridge daemon runtime ancestor must be owned by root or the current user: ${candidatePath}`)
+    }
+
+    if (candidatePath !== absolutePath && writableByOthers && !sticky) {
+      throw new Error(`Rollbridge daemon runtime ancestor must be sticky or not writable by group or other users: ${candidatePath}`)
+    }
+  }
+
+  const stats = await fs.lstat(absolutePath)
+
+  if (typeof process.getuid === "function" && stats.uid !== process.getuid()) {
+    throw new Error(`Rollbridge daemon runtime path must be owned by the current user: ${absolutePath}`)
+  }
+
+  if ((stats.mode & 0o022) !== 0) {
+    throw new Error(`Rollbridge daemon runtime path must not be writable by group or other users: ${absolutePath}`)
+  }
+}
+
+/**
+ * Reads and validates the runtime identity supplied to a detached daemon.
+ * @param {string | undefined} manifestPath - Runtime manifest path.
+ * @returns {Promise<DaemonRuntimeIdentity>} Validated identity.
+ */
+export async function loadDaemonRuntimeIdentity(manifestPath) {
+  if (!manifestPath) return await currentPackageIdentity()
+
+  const runtimePath = path.dirname(manifestPath)
+  const identity = parseIdentity(JSON.parse(await fs.readFile(manifestPath, "utf8")))
+
+  if (path.resolve(identity.path) !== path.resolve(runtimePath)) {
+    throw new Error(`Daemon runtime manifest path mismatch: expected ${runtimePath}, got ${identity.path}`)
+  }
+
+  await validateRuntime(runtimePath, identity)
+  return identity
+}
+
+/**
+ * @returns {Promise<DaemonRuntimeIdentity>} Identity of the package running a foreground daemon.
+ */
+export async function currentPackageIdentity() {
+  return {
+    digest: await packageClosureDigest(packageRoot),
+    format: RUNTIME_FORMAT,
+    path: packageRoot,
+    version: await packageVersion(packageRoot)
+  }
+}
+
+/**
+ * @param {string} sourcePath - Source package directory.
+ * @param {string} destinationPath - Destination package directory.
+ * @param {Set<string>} ancestry - Real package paths in the current dependency chain.
+ * @param {boolean} root - Whether this is Rollbridge itself.
+ * @returns {Promise<void>} Resolves when copied.
+ */
+async function copyPackageClosure(sourcePath, destinationPath, ancestry, root) {
+  const realSourcePath = await fs.realpath(sourcePath)
+
+  if (ancestry.has(realSourcePath)) return
+
+  const nextAncestry = new Set(ancestry).add(realSourcePath)
+  const packageJson = JSON.parse(await fs.readFile(path.join(realSourcePath, "package.json"), "utf8"))
+
+  await fs.mkdir(destinationPath, {recursive: true})
+
+  if (root) {
+    for (const entry of ["bin", "src", "package.json"]) {
+      await fs.cp(path.join(realSourcePath, entry), path.join(destinationPath, entry), {dereference: true, recursive: true})
+    }
+  } else {
+    await fs.cp(realSourcePath, destinationPath, {
+      dereference: true,
+      filter: (source) => path.relative(realSourcePath, source).split(path.sep)[0] !== "node_modules",
+      recursive: true
+    })
+  }
+
+  for (const dependency of Object.keys(packageJson.dependencies || {}).sort()) {
+    const dependencySource = await resolvePackageRoot(realSourcePath, dependency)
+    const dependencyDestination = path.join(destinationPath, "node_modules", ...dependency.split("/"))
+
+    await copyPackageClosure(dependencySource, dependencyDestination, nextAncestry, false)
+  }
+}
+
+/**
+ * @param {string} parentPackagePath - Requiring package root.
+ * @param {string} dependency - Dependency package name.
+ * @returns {Promise<string>} Resolved dependency package root.
+ */
+async function resolvePackageRoot(parentPackagePath, dependency) {
+  const require = createRequire(path.join(parentPackagePath, "package.json"))
+  let candidate = path.dirname(require.resolve(dependency))
+
+  while (candidate !== path.dirname(candidate)) {
+    try {
+      const metadata = JSON.parse(await fs.readFile(path.join(candidate, "package.json"), "utf8"))
+
+      if (metadata.name === dependency) return candidate
+    } catch (error) {
+      if (!hasCode(/** @type {Error & {code?: string}} */ (error), "ENOENT")) throw error
+    }
+
+    candidate = path.dirname(candidate)
+  }
+
+  throw new Error(`Unable to resolve package root for Rollbridge runtime dependency ${dependency}`)
+}
+
+/**
+ * @param {string} runtimePath - Runtime directory.
+ * @param {DaemonRuntimeIdentity} identity - Expected identity.
+ * @returns {Promise<void>} Resolves when valid.
+ */
+async function validateRuntime(runtimePath, identity) {
+  const manifestIdentity = parseIdentity(JSON.parse(await fs.readFile(path.join(runtimePath, "runtime.json"), "utf8")))
+  const actualDigest = await directoryDigest(runtimePath, new Set(["runtime.json"]))
+  const actualVersion = await packageVersion(runtimePath)
+  const manifestMatches = manifestIdentity.format === identity.format && manifestIdentity.digest === identity.digest &&
+    manifestIdentity.version === identity.version && path.resolve(manifestIdentity.path) === path.resolve(identity.path)
+
+  if (!manifestMatches || identity.format !== RUNTIME_FORMAT || actualDigest !== identity.digest || actualVersion !== identity.version) {
+    throw new Error(`Rollbridge daemon runtime validation failed at ${runtimePath}`)
+  }
+
+  await execFileAsync(process.execPath, [path.join(runtimePath, "bin", "rollbridge"), "--help"], {
+    env: {...process.env, ROLLBRIDGE_DAEMON_RUNTIME_MANIFEST: path.join(runtimePath, "runtime.json")},
+    timeout: 10000
+  })
+}
+
+/**
+ * @param {string} sourcePath - Package root.
+ * @returns {Promise<string>} Closure digest.
+ */
+async function packageClosureDigest(sourcePath) {
+  const temporaryPath = await fs.mkdtemp(path.join(os.tmpdir(), "rollbridge-digest-"))
+
+  try {
+    await copyPackageClosure(sourcePath, temporaryPath, new Set(), true)
+    return await directoryDigest(temporaryPath)
+  } finally {
+    await fs.rm(temporaryPath, {force: true, recursive: true})
+  }
+}
+
+/**
+ * @param {string} rootPath - Directory to hash.
+ * @param {Set<string>} [ignored] - Root-relative paths to ignore.
+ * @returns {Promise<string>} SHA-256 digest.
+ */
+async function directoryDigest(rootPath, ignored = new Set()) {
+  const hash = createHash("sha256")
+
+  for (const relativePath of await listFiles(rootPath)) {
+    if (ignored.has(relativePath)) continue
+    const filePath = path.join(rootPath, relativePath)
+    hash.update(relativePath)
+    hash.update("\0")
+    hash.update(await fs.readFile(filePath))
+    hash.update("\0")
+  }
+
+  return hash.digest("hex")
+}
+
+/**
+ * @param {string} rootPath - Directory to walk.
+ * @returns {Promise<string[]>} Sorted files.
+ */
+async function listFiles(rootPath) {
+  /** @type {string[]} */
+  const files = []
+
+  /**
+   * @param {string} relativePath - Root-relative directory.
+   * @returns {Promise<void>} Resolves after walking the directory.
+   */
+  async function walk(relativePath) {
+    const entries = await fs.readdir(path.join(rootPath, relativePath), {withFileTypes: true})
+
+    for (const entry of entries.sort((first, second) => first.name.localeCompare(second.name))) {
+      const childPath = path.join(relativePath, entry.name)
+
+      if (entry.isDirectory()) await walk(childPath)
+      else if (entry.isFile()) files.push(childPath)
+      else throw new Error(`Unsupported entry in Rollbridge runtime: ${path.join(rootPath, childPath)}`)
+    }
+  }
+
+  await walk("")
+  return files
+}
+
+/**
+ * @param {string} rootPath - Package root.
+ * @returns {Promise<string>} Package version.
+ */
+async function packageVersion(rootPath) {
+  const metadata = JSON.parse(await fs.readFile(path.join(rootPath, "package.json"), "utf8"))
+
+  if (typeof metadata.version !== "string" || metadata.version.length === 0) throw new Error("Rollbridge package version is missing")
+  return metadata.version
+}
+
+/**
+ * @param {import("./json.js").JsonValue} value - Parsed manifest.
+ * @returns {DaemonRuntimeIdentity} Valid identity.
+ */
+function parseIdentity(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error("Invalid Rollbridge daemon runtime manifest")
+
+  const identity = /** @type {Record<string, import("./json.js").JsonValue>} */ (value)
+
+  if (identity.format !== RUNTIME_FORMAT || typeof identity.digest !== "string" || !/^[a-f0-9]{64}$/.test(identity.digest) || typeof identity.path !== "string" || typeof identity.version !== "string") {
+    throw new Error("Invalid Rollbridge daemon runtime manifest")
+  }
+
+  return {digest: identity.digest, format: identity.format, path: identity.path, version: identity.version}
+}
+
+/**
+ * @param {Error & {code?: string} | null | undefined} error - Error.
+ * @param {string} code - Error code.
+ * @returns {boolean} Whether it matches.
+ */
+function hasCode(error, code) {
+  return Boolean(error && typeof error === "object" && "code" in error && error.code === code)
+}