rollbridge 0.1.39 → 0.1.40

package/README.md

@@ -227,7 +227,13 @@ then runs a private local process guardian which remains the OS supervisor for
 managed processes if the control daemon exits unexpectedly. A replacement using
 the exact same normalized config/runtime reconnects within `reconnectGraceMs`,
 reconstructs active and draining generations and their ports, and fences
-concurrent replacements. `ensure-daemon` can also prepare a requested
+concurrent replacements. If no replacement reconnects during that grace, the
+guardian restarts the exact accepted daemon command and environment itself; the
+recovery definition is kept only in the guardian's private authenticated state
+and is refreshed atomically during a package/runtime replacement. A restart
+attempt which cannot claim ownership and publish ready listeners within the
+accepted startup timeout is terminated with its process group and retried with a
+nonzero backoff. `ensure-daemon` can also prepare a requested
 config/control-socket/package/runtime owner, prove it healthy, and atomically
 transfer guardian authority while every retained generation keeps its exact
 release reference and drains asynchronously. The old `statePath` is the durable
@@ -237,6 +243,15 @@ Prepared transactions fence owner mutations and compare a monotonic guardian
 state revision at staging. Existing HTTP/WebSocket connections remain owned by
 the retired listener process, while their counts transfer to the new daemon so
 later deploys continue to honor the original drain boundary.
+If that new daemon itself exits while a retired listener still owns connections,
+recovery conservatively retains the last authenticated transferred count until
+the configured drain timeout; it never guesses that the older sockets closed.
+An intermediate guardian which supports atomic owner replacement but predates
+daemon recovery cannot be hot-upgraded because it is the existing processes' OS
+supervisor. The upgrade fails before handoff and requires one explicit clean
+`shutdown` followed by `ensure-daemon`; subsequent package/runtime replacements
+remain atomic. A genuinely pre-replacement guardian still uses the separately
+documented one-time disruptive compatibility bridge below.
 
 There is one explicit compatibility boundary: the first upgrade from a genuine
 pre-owner-replacement Rollbridge guardian and daemon cannot share its listeners
@@ -425,10 +440,13 @@ If the new release fails to start or health-check, the previous release stays
 active and any service started during this deploy is rolled back.
 
 `status.releaseReferences` lists the id and path of every active or draining
-release. A reference disappears only when that release is fully stopped. With
+release, plus a stopped release that still owns a persistent service definition
+or singleton, or remains part of an unresolved generation transition. A
+reference disappears only when that release has stopped and no longer owns
+runtime state. With
 `ownerRecovery`, those references and generations survive both same-authority
-daemon recovery and guardian-fenced incompatible config/control-socket/package/
-runtime replacement through `ensure-daemon`.
+daemon recovery and guardian-fenced incompatible
+config/control-socket/package/runtime replacement through `ensure-daemon`.
 
 ## Commands
 

package/changelog.d/20260830-guardian-retired-replacement-process-key.md

@@ -7,10 +7,21 @@
 - Fail closed when an older retained guardian cannot commit that replacement
   atomically after the incumbent control socket disappears, preserving the
   incumbent owner, retained connections, and guardian-managed release processes.
+- Retire the committed incumbent listener after a control-socket-absent handoff
+  only after relaying source-identified live connection counts through successive
+  owner replacements. Existing WebSocket connections can finish draining without
+  one retired listener clearing another listener's counts, and socket-path cleanup
+  remains fenced by the listener identity that was actually bound.
+- Keep incumbent authority while it yields a fixed proxy, commit only after the
+  candidate receives complete listener state and binds successfully, and resume
+  the incumbent if that bind fails. Pending retirement survives candidate recovery,
+  concurrent replacements remain fenced, and crashed local sources publish zero
+  tombstones while stopped zero-count releases remain omitted.
 - Explicitly classify retained guardian replacement capabilities before preparing
   a transaction. Guardians with prepare/stage support but no retired-owner commit
   command use the fully attested one-time disruptive legacy upgrade bridge;
   malformed, stale, or ambiguous protocol responses continue to fail closed. The
   partial guardian's prepared transaction remains the mutation fence through
   candidate reconstruction and boundary revalidation, and failed preparation
-  notifies the incumbent to resume paused release drains.
+  notifies the incumbent to resume paused release drains. The bridge coordinator
+  publishes its own authenticated recovery identity before the candidate proceeds.

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

@@ -5,5 +5,19 @@
   candidate-activate acknowledgement, and synchronous active/proxy commit with
   exact transition recovery and resume. Exact release definitions remain private
   to guardian recovery, post-commit singleton work is resumable, unresolved
-  control mutations are fenced, and an active coordinator restores its role after
-  restart. Hook-free configs keep their existing deploy behavior.
+  control and terminal owner mutations are fenced, recovery uses a complete
+  monotonic journal and publishes listener/PID readiness before replaying long
+  hooks, signals shut down cleanly after replay, and an active coordinator
+  restores its role after restart. Public recovery state advances only after its
+  private guardian authority, persistent service definitions retain their exact
+  release across recovery, manual restart reaches the active handoff coordinator,
+  unresolved transitions retain both release definitions and reject
+  config-authority-changing owner replacements, and live activation-mode changes
+   require a daemon restart. Hook-free configs keep their existing deploy behavior.
+
+### Fixed
+
+- Serialize active-role restoration with retirement, reject empty lifecycle
+  commands, bound guardian process-log forwarding for stalled clients, and keep
+  a claimed recovery owner alive until replacement listener retirement. Journal
+  hook-free post-switch retirement and singleton work for exact crash recovery.

package/changelog.d/20260830055159-guardian-daemon-restart.md

@@ -0,0 +1,2 @@
+- Let an `ownerRecovery` process guardian restart the exact accepted Rollbridge daemon command and environment after the reconnection grace when no external replacement claims ownership. Active and draining managed processes keep their existing PIDs, foreground or configured daemon log destinations remain current, the guardian atomically publishes PID files only for ready owners, startup fencing lasts through listener readiness, failed or superseded process groups are terminated, failed starts use a nonzero retry backoff, diagnostics exclude private recovery values, relative control/state paths resolve from the durable config directory, ensured daemons recover from that directory rather than a removable release cwd, and atomic package/runtime replacement refreshes the guardian's private recovery definition.
+- Require one explicit clean shutdown and restart when upgrading an intermediate persistent guardian that supports owner replacement but predates daemon recovery, because the existing OS supervisor cannot gain daemon-recovery code through an ordinary daemon-only handoff. Genuinely pre-replacement guardians retain their one-time disruptive compatibility bridge.

package/docs/cli.md

@@ -99,8 +99,11 @@ rollbridge ensure-daemon [--config <path>]
 ```
 
 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.
+already accepting commands, waits until it responds and its guardian accepts
+the ready owner, then prints the daemon status JSON. Idempotent — safe to call
+before every deploy. The detached daemon uses the config file's directory as its
+working directory, rather than the invoking release, so release retention cannot
+remove the accepted recovery cwd.
 
 Before starting a detached daemon, Rollbridge atomically copies its runtime code
 and production dependency closure into a content-addressed directory outside
@@ -128,8 +131,8 @@ and authority failures do not qualify and fail before any deploy is sent.
   [`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`. During replacement, the file
-  continues to name the incumbent until the reachable winner reports and
-  publishes its exact `daemonPid`.
+  continues to name the incumbent until the authenticated guardian atomically
+  publishes the ready winner's exact `daemonPid`.
 - `--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
@@ -167,10 +170,16 @@ An unresolved failure blocks different deploys; only the exact same release,
 path, revision, and config authority may explicitly resume its incomplete
 idempotent phase. A durable `committed_pending` phase keeps exact retry from
 reporting success until singleton replacement finishes. Stop, restart, and
-rollback mutations are rejected while the transition is unresolved. Hook-free
-configs retain the existing post-activation quiet behavior and retirement result.
-`status.releaseReferences` lists `{releaseId, releasePath}` for every active or
-draining release and excludes fully stopped history.
+rollback mutations are rejected while the transition is unresolved. Automatic
+replay also fences `shutdown` and `retire-owner` until the replay attempt settles.
+An owner replacement may change runtime/package identity during an unresolved
+transition, but it cannot change config authority until that transition commits;
+the incumbent owner remains in place when such a replacement is rejected.
+Hook-free configs retain the existing post-activation quiet behavior and
+retirement result. `status.releaseReferences` lists `{releaseId, releasePath}`
+for every active or draining release and for a stopped release that still owns a
+persistent service definition, pending singleton, or unresolved generation
+transition; unrelated fully stopped history is excluded.
 
 For hook-free configs, after candidate activation `Daemon.deploy()` begins old-generation retirement
 and asynchronous drain before awaiting singleton replacement. A singleton
@@ -244,6 +253,9 @@ Memory-supervised processes also report `rssBytes`, `memoryRestarts`,
 `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.
+With `ownerRecovery`, `ownerRecovery.ready` becomes `true` only after the
+guardian has accepted that daemon's listener readiness and atomically published
+its configured PID file; `ensure-daemon` does not return a pre-ready status.
 
 A foreground known-release daemon also reports the exact CLI bootstrap identity:
 
@@ -302,7 +314,9 @@ Targeting it (by id or `--policy proxied`) is an error; use `rollbridge deploy`
 for a zero-downtime replacement. `--process <id>` with an id that is not a
 managed process (unknown, or a companion with no active release) is also an
 error. Restarting a `service` bounces a shared broker (for example Velocious
-Beacon), which briefly disrupts every process that depends on it.
+Beacon), which briefly disrupts every process that depends on it. For a handoff
+service, restart targets only the active release's instance and restores its
+active lifecycle role before reporting success.
 
 ## `predeploy-cleanup`
 

package/docs/config.md

@@ -50,13 +50,13 @@ restart.
 | `proxy` | object | **required** | Proxy listener and shared defaults (see below). |
 | `processes` | array | **required** | Managed processes (see below). Exactly one must be `proxied`. |
 | `releaseRetention` | object | — | How many stopped releases the daemon retains (see below). |
-| `statePath` | string | unset (no persistence) | File the daemon persists its state to, enabling orphaned-process detection on the next startup (see [`statePath`](#statepath)). |
+| `statePath` | string | unset (no persistence) | File the daemon persists its state to, enabling orphaned-process detection on the next startup; relative paths resolve from the config file directory (see [`statePath`](#statepath)). |
 
 ## `control`
 
 | Field | Type | Default | Description |
 | --- | --- | --- | --- |
-| `control.path` | string | `/tmp/rollbridge-<application>.sock` | Unix domain socket the CLI uses to talk to the daemon. |
+| `control.path` | string | `/tmp/rollbridge-<application>.sock` | Unix domain socket the CLI uses to talk to the daemon; relative paths resolve from the config file directory. |
 | `control.mode` | octal string (e.g. `"660"`) or octal number (`0o660`) | unset | `chmod` applied to the socket after it binds, to share it with a deploy group. When unset, the daemon umask applies. |
 | `control.owner` | non-negative integer uid or user name | unset | `chown` owner applied to the socket after it binds. |
 | `control.group` | non-negative integer gid or group name | unset | `chown` group applied to the socket after it binds, so a shared deploy group can use it. |
@@ -126,15 +126,30 @@ ownerRecovery: {reconnectGraceMs: 30000}
 The private guardian socket is derived from `statePath`; the atomic state file is
 written mode `0600` and contains its authentication capability. The guardian
 owns managed child processes, restart policy, lifecycle hooks, and exit events.
-After an unexpected daemon exit, an exact config/runtime replacement claims the
-guardian during `reconnectGraceMs`, restores active and draining releases with
-their allocated ports, and resumes proxy/control ownership. Concurrent matching
-starts are fenced: one claims ownership and losers attest that winner. A config
-identity mismatch or partial state fails closed without rewriting the snapshot.
-Owner disconnection alone never reclaims accepted work or transfers workers:
-guardian-owned processes and their generation-local connections continue during
-the grace, so the replacement reconnects to supervision rather than duplicating
-execution.
+After an unexpected daemon exit, an exact config/runtime replacement may claim
+the guardian during `reconnectGraceMs`. If none does, the guardian restarts the
+exact accepted daemon command and environment itself, retains startup fencing
+until that daemon publishes its ready listeners and PID file, and uses a nonzero
+retry backoff after failed starts. The replacement restores active and draining
+releases with their allocated ports and resumes proxy/control ownership.
+An unfailed durable generation transition resumes under the guardian's mutation
+fence after those listeners and the recovered PID are ready, so a valid long
+lifecycle hook does not consume the daemon startup deadline. Status remains
+available during replay while competing mutations and terminal owner operations
+stay fenced. `SIGINT` and `SIGTERM` wait for that startup replay before beginning
+clean shutdown. Transition snapshots carry a monotonic journal revision; the
+public snapshot is considered only when it is strictly newer and contains every
+retained transition and singleton-owning release, while private guardian state
+remains authoritative on ties and for older released snapshots without a
+journal revision.
+Concurrent matching starts are fenced: one claims ownership and losers attest
+that winner. The authenticated guardian's private committed state is
+authoritative when the public snapshot is stale or partially written; missing or
+corrupt guardian identity, authentication, or authority still fails closed
+without rewriting the snapshot. Owner disconnection alone never reclaims
+accepted work or transfers workers: guardian-owned processes and their
+generation-local connections continue during the grace, so the replacement
+reconnects to supervision rather than duplicating execution.
 
 For a responsive incompatible owner, `ensure-daemon` prepares the requested
 durable runtime, restores exact active and draining generation definitions from
@@ -163,6 +178,13 @@ identity; retry config or socket changes after the protocol upgrade, when the
 normal atomic handoff applies. Other guardian/auth/transport/identity failures
 remain fail-closed.
 
+An intermediate guardian which already supports atomic owner replacement but
+predates guardian-owned daemon recovery cannot be upgraded through that bridge.
+The candidate aborts before listener handoff, the incumbent resumes any paused
+drains and remains serving, and the command requests one explicit clean
+`shutdown` followed by `ensure-daemon` so the new guardian can become the OS
+supervisor.
+
 Without `ownerRecovery`, `statePath` retains the advisory orphan behavior above.
 
 ## `legacyTakeover`
@@ -293,7 +315,9 @@ release id, path, revision, and config may resume only its incomplete idempotent
 phase. Once the health-ready candidate is journaled, its exact config becomes the
 transition authority even if a later hook fails. A recorded failed hook is not
 retried merely because daemon ownership changes. Omit `activateCommand` to retain
-the existing activate-then-retire behavior.
+the existing activate-then-retire behavior. Adding, removing, or moving
+`activateCommand` changes the daemon's generation coordinator and therefore
+requires a daemon restart before the next deploy.
 
 The synchronous traffic assignment is persisted as `committed_pending` before
 Rollbridge awaits singleton replacement. Exact retry or unambiguous owner recovery
@@ -469,6 +493,6 @@ Rollbridge sets these in every managed process's environment (the process's own
 - `restart.maxRestarts` must be a non-negative integer (omit it for unlimited restarts); `restart.backoffFactor` must be a number ≥ 1; `restart.windowMs` and `restart.maxDelayMs` must be non-negative numbers.
 - When `memory` is set, `memory.limitBytes` must be a positive integer, `memory.warnBytes` a non-negative integer, and `memory.checkIntervalMs` a positive number.
 - `replicas` must be a positive integer; `replicas > 1` is allowed only on a `companion` process without a `port`. Process ids must not contain `#` (reserved for replica instance ids).
-- `lifecycle.activateCommand`/`quietCommand`/`drainCommand`/`stopCommand` must be strings when set, and `lifecycle.drainTimeoutMs` a non-negative number; `lifecycle.drainCommand` requires a positive `lifecycle.drainTimeoutMs`. `activateCommand` is allowed on at most one handoff service, requires that service's `quietCommand`, and requires `statePath` plus `ownerRecovery`. A `lifecycle.stopCommand` may not be combined with a custom `stopSignal` (the `stopCommand` runs instead of the signal, so the signal would be ignored).
+- `lifecycle.activateCommand`/`quietCommand`/`drainCommand`/`stopCommand` must be non-empty strings when set, and `lifecycle.drainTimeoutMs` a non-negative number; `lifecycle.drainCommand` requires a positive `lifecycle.drainTimeoutMs`. `activateCommand` is allowed on at most one handoff service, requires that service's `quietCommand`, and requires `statePath` plus `ownerRecovery`. A `lifecycle.stopCommand` may not be combined with a custom `stopSignal` (the `stopCommand` runs instead of the signal, so the signal would be ignored).
 - `nonBlockingDrain` must be a boolean, and is allowed only on a `companion` process.
 - `statePath` must be a string when set.

package/docs/logging.md

@@ -15,7 +15,7 @@ daemon was started.
 
 | How the daemon runs | Destination |
 | --- | --- |
-| `rollbridge daemon` (foreground) | stdout — redirect it (`rollbridge daemon … >> /var/log/rollbridge/app.log 2>&1`) or let your service manager capture it. |
+| `rollbridge daemon` (foreground) | stdout — redirect it (`rollbridge daemon … >> /var/log/rollbridge/app.log 2>&1`) or let your service manager capture it. With `ownerRecovery`, guardian restarts inherit that same accepted destination. |
 | systemd (`examples/rollbridge.service`) | the journal — `journalctl -u rollbridge`. journald rotates on its own. |
 | `rollbridge ensure-daemon` / `rollbridge deploy --ensure-daemon` | the **daemon log file**: `--daemon-log-path <path>`, default `/tmp/rollbridge-<application>.log`. The detached daemon's stdout and stderr are appended there. |
 
@@ -46,8 +46,9 @@ protected accordingly.
 
 Without `ownerRecovery`, both in-memory views clear when the daemon restarts.
 With it, guardian-held process output remains available after reconnection while
-the replacement daemon begins a new event history. The configured log file
-persists in either mode.
+the replacement daemon begins a new event history. A detached ensured daemon
+keeps appending to its configured log file, while a recovered foreground daemon
+inherits its original stdout/stderr destination.
 
 ## Rotation
 

package/docs/troubleshooting.md

@@ -138,11 +138,13 @@ end close idle WebSockets on deploy). In the documented compliant jobs topology,
 jobs companions use `nonBlockingDrain: true`, so timeout expiry affects only the
 web side and must not stop a still-draining jobs generation.
 
-`status.releaseReferences` reports active and draining releases until full stop;
-Rampway still owns enforcement against on-disk cleanup. With `ownerRecovery`,
-references reconstruct across same-authority daemon process replacement and
-transfer across an incompatible `ensure-daemon` owner handoff. They do not
-transfer through the separate destructive `--takeover-owner` path. If
+`status.releaseReferences` reports active and draining releases, plus a stopped
+release that still owns a persistent service definition, pending singleton, or
+unresolved generation transition, until all runtime ownership ends; Rampway
+still owns enforcement against on-disk cleanup. With `ownerRecovery`, references
+reconstruct across same-authority daemon process replacement and transfer across
+an incompatible `ensure-daemon` owner handoff. They do not transfer through the
+separate destructive `--takeover-owner` path. If
 `retirementError` is set,
 inspect the quiet-hook events. Rollbridge deliberately leaves that generation
 alive rather than signaling arbitrary PIDs or continuing its stop sequence.

package/package.json

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

package/src/cli.js

@@ -41,37 +41,71 @@ export async function runCli(argv) {
     .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("--guardian-daemon-log-path <path>").hideHelp())
+    .addOption(new Option("--guardian-daemon-pid-path <path>").hideHelp())
+    .addOption(new Option("--guardian-daemon-start-timeout-ms <ms>").hideHelp())
     .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 recoveryEnvironment = /** @type {Record<string, string>} */ (Object.fromEntries(Object.entries(process.env).filter((entry) => entry[1] !== undefined)))
+      const recoveryLogPath = options.guardianDaemonLogPath ? path.resolve(options.guardianDaemonLogPath) : undefined
+      const recoveryPidPath = options.guardianDaemonPidPath ? path.resolve(options.guardianDaemonPidPath) : undefined
+      const recoveryStartupTimeoutMs = normalizeTimeoutMs(options.guardianDaemonStartTimeoutMs)
       const daemon = new RollbridgeDaemon({
         bootstrap,
         config,
         configPath,
         legacyIncumbentPid: positiveIntegerOrUndefined(options.legacyIncumbentPid, "legacy incumbent pid"),
+        recoveryCommand: {
+          args: [
+            path.resolve(argv[1]), "daemon", "--config", configPath,
+            ...(recoveryLogPath ? ["--guardian-daemon-log-path", recoveryLogPath] : []),
+            ...(recoveryPidPath ? ["--guardian-daemon-pid-path", recoveryPidPath] : []),
+            "--guardian-daemon-start-timeout-ms", String(recoveryStartupTimeoutMs)
+          ],
+          cwd: process.cwd(),
+          env: recoveryEnvironment,
+          executable: process.execPath,
+          logPath: recoveryLogPath,
+          pidPath: recoveryPidPath,
+          startupTimeoutMs: recoveryStartupTimeoutMs
+        },
         runtime
       })
+      let startupPromise = Promise.resolve()
+      let shutdownRequested = false
+      const shutdown = async () => {
+        shutdownRequested = true
+        await startupPromise.catch(() => undefined)
+        await daemon.shutdown()
+        process.exit(0)
+      }
+
+      process.once("SIGINT", () => { void shutdown() })
+      process.once("SIGTERM", () => { void shutdown() })
 
       if (options.takeoverOwner && (!bootstrap || !bootstrap.attestation)) throw new Error("Daemon --takeover-owner requires the complete bootstrap release tuple and --boot-attestation.")
 
       if (options.replaceOwner) {
         if (bootstrap || options.takeoverOwner) throw new Error("Daemon --replace-owner cannot be combined with bootstrap takeover options.")
-        await daemon.replaceIncompatibleOwner()
+        startupPromise = daemon.replaceIncompatibleOwner()
+        await startupPromise
       }
 
       if (!options.takeoverOwner && !options.replaceOwner) {
         try {
-          await daemon.start({exposeControl: !bootstrap})
+          startupPromise = daemon.start({exposeControl: !bootstrap})
+          await startupPromise
         } 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() &&
+            winner.ownerRecovery.configDigest === daemon.ownerRecoveryConfigDigest() && winner.ownerRecovery.ready === true &&
             ((!runtime && !winner.daemonRuntime) || (runtime && winner.daemonRuntime && typeof winner.daemonRuntime === "object" && !Array.isArray(winner.daemonRuntime) && winner.daemonRuntime.digest === runtime.digest))
 
           if (!matchingWinner) throw error
@@ -79,14 +113,7 @@ export async function runCli(argv) {
           return
         }
       }
-
-      const shutdown = async () => {
-        await daemon.shutdown()
-        process.exit(0)
-      }
-
-      process.once("SIGINT", () => { void shutdown() })
-      process.once("SIGTERM", () => { void shutdown() })
+      if (shutdownRequested) return
 
       if (bootstrap) {
         try {
@@ -105,6 +132,7 @@ export async function runCli(argv) {
           if (config.ownerRecovery && daemon.releases.size > 0) {
             if (daemon.activeRelease) {
               await daemon.exposeControl()
+              await publishDaemonReadiness(daemon, recoveryPidPath)
               return
             }
             await daemon.abandonOwnerRecoveryAttempt()
@@ -124,6 +152,7 @@ export async function runCli(argv) {
           return
         }
       }
+      if (!shutdownRequested) await publishDaemonReadiness(daemon, recoveryPidPath)
     })
 
   program
@@ -839,6 +868,8 @@ async function validateDaemonBootstrapOptions(options) {
  */
 async function ensureDaemonRunning({config, configPath, logPath, pidPath, runtimePath, timeoutMs}) {
   const runtime = await prepareDaemonRuntime(runtimePath || defaultDaemonRuntimePath(config))
+  const resolvedConfigPath = path.resolve(configPath)
+  const resolvedLogPath = path.resolve(logPath || defaultDaemonLogPath(config))
   const existingStatus = await daemonStatus(config)
   const expectedConfigDigest = ownerConfigDigest(config)
 
@@ -848,26 +879,30 @@ async function ensureDaemonRunning({config, configPath, logPath, pidPath, runtim
       existingStatus.ownerRecovery.configDigest === expectedConfigDigest
     )
 
-    if (compatibleDaemonRuntime(existingStatus, runtime) && matchingRecoveryAuthority) return existingStatus
+    if (compatibleDaemonRuntime(existingStatus, runtime) && matchingRecoveryAuthority) {
+      if (!config.ownerRecovery || (existingStatus.ownerRecovery && typeof existingStatus.ownerRecovery === "object" && !Array.isArray(existingStatus.ownerRecovery) && existingStatus.ownerRecovery.ready === true)) return existingStatus
+      return await waitForDaemonStatus(config, timeoutMs, {configDigest: expectedConfigDigest, runtime})
+    }
     if (!config.ownerRecovery) assertCompatibleDaemonRuntime(existingStatus, runtime)
   }
 
   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 replacement = Boolean(config.ownerRecovery && (existingStatus || (persistedRecovery && typeof persistedRecovery === "object" && !Array.isArray(persistedRecovery))))
+  const resolvedPidPath = path.resolve(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),
+    configPath: resolvedConfigPath,
+    cwd: path.dirname(resolvedConfigPath),
+    logPath: resolvedLogPath,
+    pidPath: resolvedPidPath,
     replacement,
     legacyIncumbentPid,
-    runtime
+    runtime,
+    timeoutMs
   })
   let startedStatus
 
@@ -885,8 +920,11 @@ async function ensureDaemonRunning({config, configPath, logPath, pidPath, runtim
     )
 
     if (!startedPid) throw new Error("Started Rollbridge daemon did not report its exact PID")
-    await fsPromises.writeFile(resolvedPidPath, `${startedPid}\n`)
+    if (!config.ownerRecovery) await fsPromises.writeFile(resolvedPidPath, `${startedPid}\n`)
     return startedStatus
+  } catch (error) {
+    killDetachedProcessGroup(candidate)
+    throw error
   } finally {
     candidate.unref()
   }
@@ -917,13 +955,16 @@ async function daemonStatus(config) {
  * Starts the foreground daemon command as a detached child.
  * @param {object} args - Options.
  * @param {string} args.configPath - Config path.
+ * @param {string} args.cwd - Durable daemon working directory.
  * @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.
+ * @param {number} args.timeoutMs - Guardian recovery startup timeout.
  * @returns {Promise<import("node:child_process").ChildProcess>} Referenced child after exact spawn completion.
  */
-async function startDaemonProcess({configPath, legacyIncumbentPid, logPath, replacement = false, runtime}) {
+async function startDaemonProcess({configPath, cwd, legacyIncumbentPid, logPath, pidPath, replacement = false, runtime, timeoutMs}) {
   await fsPromises.mkdir(path.dirname(logPath), {recursive: true})
 
   const stdoutFd = fs.openSync(logPath, "a")
@@ -932,9 +973,13 @@ async function startDaemonProcess({configPath, legacyIncumbentPid, logPath, repl
   try {
     const child = spawn(process.execPath, [
       path.join(runtime.path, "bin", "rollbridge"), "daemon", "--config", configPath,
+      "--guardian-daemon-log-path", logPath,
+      "--guardian-daemon-pid-path", pidPath,
+      "--guardian-daemon-start-timeout-ms", String(timeoutMs),
       ...(replacement ? ["--replace-owner"] : []),
       ...(legacyIncumbentPid ? ["--legacy-incumbent-pid", String(legacyIncumbentPid)] : [])
     ], {
+      cwd,
       detached: true,
       env: {...process.env, ROLLBRIDGE_DAEMON_RUNTIME_MANIFEST: path.join(runtime.path, "runtime.json")},
       stdio: ["ignore", stdoutFd, stderrFd]
@@ -1026,11 +1071,10 @@ async function waitForDaemonStatus(config, timeoutMs, expected = {}) {
 
       if (status) {
         const statusPid = typeof status.daemonPid === "number" ? status.daemonPid : undefined
-        const candidateResolved = !expected.candidate || candidateExit || statusPid === expected.candidate.pid
-
         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))) {
+        } else if (!expected.configDigest || (status.ownerRecovery && typeof status.ownerRecovery === "object" && !Array.isArray(status.ownerRecovery) && status.ownerRecovery.configDigest === expected.configDigest && status.ownerRecovery.ready === true)) {
+          if (expected.candidate && !candidateExit && statusPid !== expected.candidate.pid) killDetachedProcessGroup(expected.candidate)
           return status
         }
       }
@@ -1058,6 +1102,31 @@ async function waitForDaemonStatus(config, timeoutMs, expected = {}) {
   }
 }
 
+/**
+ * Publishes the exact daemon PID before confirming completed startup to its guardian.
+ * @param {RollbridgeDaemon} daemon - Started daemon.
+ * @param {string | undefined} pidPath - Optional daemon PID file.
+ */
+async function publishDaemonReadiness(daemon, pidPath) {
+  if (daemon.guardian) {
+    await daemon.markOwnerReady()
+  } else if (pidPath) {
+    await fsPromises.mkdir(path.dirname(pidPath), {recursive: true})
+    await fsPromises.writeFile(pidPath, `${process.pid}\n`)
+  }
+}
+
+/** @param {import("node:child_process").ChildProcess} child - Exact detached process-group leader. */
+function killDetachedProcessGroup(child) {
+  if (!child.pid) return
+  try {
+    process.kill(-child.pid, "SIGKILL")
+  } catch (error) {
+    if (error && typeof error === "object" && "code" in error && error.code === "ESRCH") return
+    throw error
+  }
+}
+
 /**
  * @param {import("node:child_process").ChildProcess} candidate - Exact spawned daemon candidate.
  * @param {{code: number | null, signal: DaemonExitSignal}} exit - Exact exit status.

package/src/config.js

@@ -67,8 +67,12 @@ export async function parseConfigFile(configPath) {
  */
 export async function loadConfig(configPath) {
   const {absolutePath, rawConfig} = await parseConfigFile(configPath)
+  const config = normalizeConfig(rawConfig, absolutePath)
+  const configDirectory = path.dirname(absolutePath)
 
-  return normalizeConfig(rawConfig, absolutePath)
+  config.control.path = path.resolve(configDirectory, config.control.path)
+  if (config.statePath) config.statePath = path.resolve(configDirectory, config.statePath)
+  return config
 }
 
 /**
@@ -351,10 +355,10 @@ function normalizeLifecycle(value, key, issues) {
   /** @type {LifecycleConfig} */
   const lifecycle = {drainTimeoutMs: nonNegativeOrDefault(drainTimeoutMs, `${key}.drainTimeoutMs`, issues, 0, false)}
 
-  if (value.activateCommand !== undefined) lifecycle.activateCommand = normalizeString(value.activateCommand, `${key}.activateCommand`, issues)
-  if (value.quietCommand !== undefined) lifecycle.quietCommand = normalizeString(value.quietCommand, `${key}.quietCommand`, issues)
-  if (value.drainCommand !== undefined) lifecycle.drainCommand = normalizeString(value.drainCommand, `${key}.drainCommand`, issues)
-  if (value.stopCommand !== undefined) lifecycle.stopCommand = normalizeString(value.stopCommand, `${key}.stopCommand`, issues)
+  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.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})
 
   if (lifecycle.drainCommand !== undefined && lifecycle.drainTimeoutMs <= 0) {
     issues.push({fix: `Set ${key}.drainTimeoutMs to a positive number to bound ${key}.drainCommand; with 0 the drain step is skipped and the command never runs.`, message: `${key}.drainCommand requires a positive ${key}.drainTimeoutMs`})
@@ -849,7 +853,7 @@ function normalizePortRange(value, key, issues) {
  * @param {JsonValue} value - Raw value.
  * @param {string} key - Config key.
  * @param {ConfigIssue[]} issues - Issue collector.
- * @param {{default?: string}} [options] - Options.
+ * @param {{default?: string, nonEmpty?: boolean}} [options] - Options.
  * @returns {string} Normalized string, or a placeholder when invalid.
  */
 function normalizeString(value, key, issues, options = {}) {
@@ -867,6 +871,10 @@ function normalizeString(value, key, issues, options = {}) {
     return options.default ?? ""
   }
 
+  if (options.nonEmpty && !value.trim()) {
+    issues.push({fix: `Set ${key} to a non-empty command string.`, message: `${key} must not be empty`})
+  }
+
   return value
 }