rollbridge 0.1.27 → 0.1.29

package/AGENTS.md

@@ -40,6 +40,20 @@ implemented. Do not claim production compliance when source/config still uses a
 fixed jobs-main, worker adoption by a new main, destructive orphan recovery, or
 synchronous cleanup.
 
+Current same-authority behavior quiesces configured handoff services after
+candidate activation, retains concurrent generations, reports live release
+references, and can opt into `ownerRecovery` so a durable process guardian
+preserves and reconstructs active/draining generations after daemon process
+exit. With `ownerRecovery` and the same `statePath` transaction anchor,
+`ensure-daemon` also replaces incompatible config, control-socket, package, and
+runtime owners through a guardian-fenced candidate-first handoff while retaining
+active and draining generations. The first authenticated upgrade from a genuine
+pre-replacement guardian/daemon is a documented disruptive compatibility bridge:
+it preserves exact supervised processes and state, but may close proxy/control
+connections. Every protocol-capable replacement after that bridge is atomic.
+`--takeover-owner` remains a destructive
+external-supervisor migration path, not that atomic handoff.
+
 ## Validation and publication
 
 The project is ESM JavaScript with JSDoc type checking. Package scripts are the

package/README.md

@@ -83,6 +83,7 @@ export default {
       deployStrategy: "handoff",
       cwd: "{{releasePath}}",
       command: "env VELOCIOUS_BACKGROUND_JOBS_PORT={{port}} npx velocious background-jobs-main",
+      lifecycle: {quietCommand: "appctl jobs-main-retire --pid $ROLLBRIDGE_PID"},
       port: {from: 7331, to: 7399}
     },
     {
@@ -97,6 +98,9 @@ export default {
 }
 ```
 
+`appctl jobs-main-retire` is illustrative; replace it with a reviewed command
+that quiesces the real jobs-main without exiting it.
+
 Each process retains its most recent stdout/stderr lines and reports them in
 `status`. Set `outputLines` (a positive integer, default 50) per process to keep
 more or fewer lines for chatty or quiet processes.
@@ -169,6 +173,13 @@ handoffs as soon as its release retires, independently of the proxied connection
 drain. Its release-scoped handoff jobs-main remains running to supervise existing
 handoffs and exits only after the worker pool has drained.
 
+Give the handoff jobs-main a `lifecycle.quietCommand` that stops schedules,
+dispatch, and new handoffs without terminating the main. After candidate health
+and traffic activation, Rollbridge waits only for this bounded quiescence step,
+then returns while the old main and workers drain together. A failed quiet hook
+is reported as `retirementError`; Rollbridge leaves that generation alive for
+diagnosis instead of silently continuing to stop it.
+
 See [`docs/workers.md`](docs/workers.md) for the full release-generation
 deployment pattern: a handoff `background-jobs-main`, its companion worker pool,
 independent quiescence, and durable supervision while retained generations drain.
@@ -184,13 +195,13 @@ owns cleaning up on-disk release directories.
 releaseRetention: {keep: 5, maxAgeMs: 86400000}
 ```
 
-Set `statePath` to have the daemon persist secret-safe recovery state to a file
+Set `statePath` to have the daemon persist sanitized recovery state to a file
 (active/draining releases, process pids, counters, sanitized recent events).
 Commands, environment mappings, child command lines, and captured process output
 are deliberately excluded; those diagnostics remain available through the live
-status/log/event APIs. On the next startup Rollbridge reads any leftover file and
-reports managed processes still alive from a daemon that didn't shut down cleanly
-— advisory orphan detection. After a crash, run
+status/log/event APIs. Without `ownerRecovery`, the next startup reads any
+leftover file and reports managed processes still alive from a daemon that
+didn't shut down cleanly — advisory orphan detection. In that mode, after a crash run
 `rollbridge recover` to list those leftovers and `rollbridge recover --force` to
 stop them before restarting the daemon. A clean `shutdown` removes the file. See
 [`docs/config.md`](docs/config.md#statepath).
@@ -199,6 +210,41 @@ stop them before restarting the daemon. A clean `shutdown` removes the file. See
 statePath: "/var/lib/rollbridge/ticket-server.state.json"
 ```
 
+For durable daemon process recovery and atomic owner replacement, opt into
+`ownerRecovery`. Rollbridge
+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
+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
+transaction anchor and cannot change during this handoff. The `0600` state file
+contains the guardian capability; protect its directory accordingly.
+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.
+
+There is one explicit compatibility boundary: the first upgrade from a genuine
+pre-owner-replacement Rollbridge guardian and daemon cannot share its listeners
+on supported Node 20. After authenticating the guardian, exact daemon PID/socket,
+runtime authority, and durable owned-process state, `ensure-daemon` performs a
+one-time **disruptive** bridge. Existing proxy/control connections may close,
+the retained processes keep their exact PIDs under guardian supervision, and
+`status.ownerTransition` reports `mode: "legacy-first-upgrade"` with
+`disruptive: true`. The bridge requires the existing config identity unchanged;
+apply config/socket changes in a subsequent invocation, which uses the atomic
+protocol. Unknown commands, auth/transport failures, malformed responses, and
+identity mismatches fail closed without entering this bridge. Every replacement
+after this protocol upgrade remains candidate-first and atomic.
+
+```js
+statePath: "/var/lib/rollbridge/ticket-server.state.json",
+ownerRecovery: {reconnectGraceMs: 30000}
+```
+
 During the first migration from an old supervisor, set `legacyTakeover` and run
 `rollbridge predeploy-cleanup --release-path <path>` before `rollbridge deploy`.
 Rollbridge will only stop configured legacy processes when no reusable active
@@ -241,7 +287,7 @@ rendered when the process starts:
 Referencing a placeholder with no value (including an unset `{{env.<NAME>}}`)
 fails the process start with a clear error, so typos surface immediately.
 
-Production-ready examples live in `examples/`, including
+Configuration examples live in `examples/`, including
 `examples/tensorbuzz.com.js` for the current TensorBuzz backend deployment; see
 [`docs/tensorbuzz-runbook.md`](docs/tensorbuzz-runbook.md) for the matching
 production runbook (ports, deploy ordering, rollback constraints, and day-to-day
@@ -338,6 +384,7 @@ candidate coordinator.
   deployStrategy: "handoff",
   cwd: "{{releasePath}}",
   command: "npx velocious background-jobs-main",
+  lifecycle: {quietCommand: "appctl jobs-main-retire --pid $ROLLBRIDGE_PID"},
   port: {from: 7331, to: 7399}
 }
 ```
@@ -350,7 +397,7 @@ On `rollbridge deploy`, the required ordering is:
 2. starts the new release's `companion`s, then its `proxied` process, and
    health-checks the proxied process;
 3. switches new traffic to the new release;
-4. marks the previous jobs-main and worker pool retired as one generation;
+4. quiesces the previous jobs-main and worker pool as one retired generation;
 5. replaces `singleton`s (stops the old one, then starts the new one);
 6. returns success without waiting for the previous generation or its independent
    HTTP/WebSocket drain; Rollbridge supervises all retained drains in the
@@ -359,6 +406,12 @@ On `rollbridge deploy`, the required ordering is:
 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
+`ownerRecovery`, those references and generations survive both same-authority
+daemon recovery and guardian-fenced incompatible config/control-socket/package/
+runtime replacement through `ensure-daemon`.
+
 ## Commands
 
 `--config` is optional for every command. When omitted, Rollbridge looks for
@@ -439,19 +492,21 @@ rollbridge daemon --config /srv/ticket-server/rollbridge.js \
 External supervisors that need to replace a foreground owner without waiting
 for retained generations to drain add `--takeover-owner`. The candidate starts
 and health-checks the exact release first. Only then does it retire the accepted
-owner's proxy/control listeners. Durable supervision of old jobs-main/worker
-generations must be preserved or transferred while the attested replacement
-binds the stable listeners; replacement does not mean full synchronous shutdown.
-Candidate bootstrap failure leaves the accepted owner untouched. This is opt-in;
-ordinary daemon bootstrap and `shutdown` keep their existing behavior.
+owner's proxy/control listeners. Candidate bootstrap failure leaves the accepted
+owner untouched. Current takeover does not preserve retained jobs generations
+or transfer listeners atomically, so it is not a zero-downtime package, config,
+or socket upgrade mechanism. Use `ownerRecovery` plus `ensure-daemon` for the
+guardian-fenced atomic replacement contract. This is opt-in; ordinary daemon
+bootstrap and `shutdown` keep their existing behavior.
 
 The four bootstrap inputs are all-or-nothing and use absolute config/release
 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.
+without `ownerRecovery`, persisted processes from a previous daemon are reported
+as advisory orphans and are never recovered or killed implicitly. With
+`ownerRecovery`, bootstrap reconnects only to the matching guardian and
+reconstructs its provenanced generations before exposing control.
 
 External supervisors may add `--boot-attestation` with exactly `sha256:` plus
 64 lowercase hexadecimal characters. After successful activation, `rollbridge

package/TODO.md

@@ -35,7 +35,10 @@ This roadmap tracks planned Rollbridge features and documentation. Rollbridge sh
   - [x] Support signal-only lifecycle steps for workers that can quiet on a Unix signal. (Per-process `stopSignal`; sent before the `SIGKILL`-after-`gracefulStopMs` fallback.)
   - [x] Add a non-blocking drain mode so a worker can quiesce at release retirement independently of the HTTP/WebSocket connection drain (`nonBlockingDrain`). This control alone does not provide durable retired-generation supervision.
   - [x] Document the required Velocious release-generation contract (`docs/velocious.md` and `docs/workers.md`) without treating documentation as proof that the runtime implements it.
-  - [ ] Implement and verify durable release-scoped jobs-main retirement: owned-handoff supervision, recovery across daemon/host replacement, multiple concurrent retired generations, and release-reference reporting for cleanup pins.
+  - [x] Implement same-owner jobs-main retirement, concurrent generations, independent drains, and live release-reference reporting.
+  - [x] Implement opt-in durable guardian recovery for exact same-authority daemon process replacement without stopping retained generations.
+  - [x] Implement guardian-fenced atomic incompatible owner/config/control-socket/package/runtime replacement without stopping retained generations.
+    - [x] Add the authenticated one-time disruptive bridge for pre-replacement guardians; all protocol-capable replacements remain atomic.
 - [x] Replicas and stable worker indexes. (Supported on port-less `companion` processes; `proxied`/`singleton`/ported processes stay single.)
   - [x] Allow one process config to start multiple replicas (`replicas`, companion-only for now).
   - [x] Expose `ROLLBRIDGE_REPLICA_INDEX`, replica count, and per-replica template context (`{{replicaIndex}}`/`{{replicaCount}}`).
@@ -43,7 +46,7 @@ This roadmap tracks planned Rollbridge features and documentation. Rollbridge sh
   - [x] Preserve readable status output for replica groups (each instance shown as `<id>#<index>`).
 - [x] Persistent daemon state and recovery.
   - [x] Persist active release, draining releases, process metadata, counters, and recent events (opt-in `statePath`; atomic snapshot on change + periodic).
-  - [x] Reconnect status to still-running child processes after daemon restart where possible. (Feasible subset: `status` now includes an `orphans` array — still-alive managed processes from the prior daemon's persisted state, re-checked each call. Full re-management/stdout-exit re-attach stays infeasible; the daemon reports them and `rollbridge recover` stops them.)
+  - [x] Reconnect to guardian-owned child processes when `ownerRecovery` is enabled; otherwise `status.orphans` retains advisory legacy behavior.
   - [x] Detect and report orphaned Rollbridge-managed processes. (On startup, reports persisted process pids that are still alive; advisory, see `statePath`.)
   - [x] Add a recovery mode for safe startup after daemon crash or machine reboot. (`rollbridge recover` lists orphaned processes from the persisted state and, with `--force`, stops them and clears the state; refuses while a daemon is running.)
 - [x] Rollback support.

package/changelog.d/20260828-atomic-owner-replacement.md

@@ -0,0 +1,22 @@
+### Added
+
+- Atomically replace incompatible config, control-socket, package, and runtime
+  owners through `ensure-daemon` when durable `ownerRecovery` is configured.
+  The guardian fences candidates, transfers exact active and draining release
+  supervision only after candidate readiness, and converges after an ambiguous
+  commit response or a crash at the committed-state boundary.
+- Bridge the first authenticated pre-replacement guardian/daemon upgrade while
+  preserving exact supervised process PIDs and release state. This one-time
+  compatibility transition is explicitly disruptive: existing proxy/control
+  connections may close and status records `legacy-first-upgrade`. Subsequent
+  protocol-capable owner replacements remain atomic, including on Node 20.
+- Fence post-prepare owner-state mutations with a guardian revision check and
+  carry incumbent listener connection counts until the old HTTP/WebSocket
+  sockets drain, so later deploys cannot stop a still-connected process early.
+- Reserve every live generation's allocated endpoints before its processes bind
+  and until that generation truly stops, and reconstruct those reservations on
+  owner recovery so overlapping jobs generations cannot reuse an endpoint.
+- Keep an exact newly spawned daemon candidate referenced until its status and
+  PID authority are verified. `ensure-daemon` now reports an exact early child
+  exit instead of leaving its top-level operation unsettled or waiting for a
+  generic readiness timeout; the healthy daemon is detached only afterward.

package/changelog.d/20260828-durable-owner-recovery.md

@@ -0,0 +1,7 @@
+### Added
+
+- Add opt-in `ownerRecovery` with a durable authenticated process guardian so an
+  exact same-authority daemon replacement reconstructs active and draining
+  generations, ports, lifecycle supervision, and release references after an
+  unexpected daemon exit. Concurrent replacements are fenced and mismatched or
+  partial recovery state fails closed.

package/changelog.d/20260828-same-owner-jobs-generations.md

@@ -0,0 +1,6 @@
+## Fixed
+
+- Quiesce release-scoped handoff services after healthy candidate activation,
+  retain them with their original workers during asynchronous drain, and report
+  active/draining release references. Cross-owner recovery and atomic owner
+  upgrades remain future work.

package/docs/cli.md

@@ -50,9 +50,9 @@ 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 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.
+release. With `ownerRecovery`, daemon startup first claims the matching guardian
+and reconstructs its active/draining generations. Without it, `statePath`
+entries remain advisory orphans for explicit recovery.
 
 `--boot-attestation` is an optional, non-secret opaque ownership token for an
 external supervisor. Its canonical format is exactly `sha256:` followed by 64
@@ -73,9 +73,10 @@ preserves nor transfers retained-generation supervision to the replacement.
 The replacement can bind before those stops finish. A bootstrap failure occurs
 before retirement, so the previously accepted owner remains available.
 
-A compliant future owner handoff must instead preserve or transfer durable
-supervision of retained generations without handing old workers to a new
-jobs-main. Current `--takeover-owner` does not provide that behavior.
+`ownerRecovery` covers unexpected process exit under the exact same authority.
+Guardian-fenced incompatible config/package/runtime/control-socket handoff is
+provided by `ensure-daemon`, not `--takeover-owner`; it preserves supervision
+without handing old workers to a new jobs-main.
 
 ## `ensure-daemon`
 
@@ -95,15 +96,29 @@ 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.
+runtime and normalized config authority match. With `ownerRecovery` and the same
+`statePath`, an incompatible config/control-socket/package/runtime owner is
+replaced candidate-first: the guardian retains active and draining generations,
+the candidate binds and validates its listeners, and an authenticated fenced
+transaction commits guardian authority and the final control socket. A lost
+control response is accepted only when the guardian confirms the exact committed
+transaction id. The first authenticated upgrade from a genuine pre-replacement
+guardian/daemon is the sole exception: `ensure-daemon` preserves its exact
+guardian-owned processes but deliberately retires the old listeners before the
+Node 20 candidate binds, so existing proxy/control connections may close.
+Successful status JSON records this as `ownerTransition.disruptive: true` and
+`ownerTransition.mode: "legacy-first-upgrade"`. This one-time bridge requires
+the incumbent config identity unchanged; make config/socket changes in a second,
+atomic invocation. Auth, transport, malformed-response, arbitrary unknown-command,
+and authority failures do not qualify and fail before any deploy is sent.
 
 - `--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`.
+  Default: `/tmp/rollbridge-<application>.pid`. During replacement, the file
+  continues to name the incumbent until the reachable winner reports and
+  publishes its 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
@@ -134,17 +149,24 @@ for old workers, jobs, or HTTP/WebSocket connections to finish. Prints
 If the new release fails to start or health-check, the previous release stays
 active and the command errors.
 
-After candidate activation, `Daemon.deploy()` synchronously waits for singleton
-replacement before starting `drainAndPrune` and returning. A replacement failure
-can therefore return a non-zero result while the candidate remains active, and a
-slow replacement delays both the response and retirement of the old release.
-
-This is a process-lifetime non-blocking drain, not durable supervision across a
-daemon or host restart. It continues across later deploys only while the same
-daemon remains alive. After a restart, surviving PIDs from persisted state are
-advisory orphans that Rollbridge cannot re-adopt; explicit `recover --force`
-stops them. Restart-surviving retained-generation ownership and recovery remain
-required future behavior.
+After activation, deploy waits for bounded quiet hooks of old handoff services
+and `nonBlockingDrain` companions, then returns without waiting for their drains.
+A failure is logged and exposed as `retirementError`; the generation stays alive.
+The successful activation response also includes
+`retirement: {status: "quiescence_failed", releaseId, error}` so callers cannot
+mistake the retirement failure for an unqualified transition.
+`status.releaseReferences` lists `{releaseId, releasePath}` for every active or
+draining release and excludes fully stopped history.
+
+After candidate activation, `Daemon.deploy()` begins old-generation retirement
+and asynchronous drain before awaiting singleton replacement. A singleton
+replacement failure can therefore return non-zero while the candidate remains
+active, but it cannot leave the old jobs generation dispatching.
+
+With `ownerRecovery`, active and draining generations remain guardian-supervised
+across unexpected same-authority daemon exit and reconstruct on replacement;
+they also transfer intact through an incompatible `ensure-daemon` owner handoff.
+Without it, surviving PIDs remain advisory orphans for `recover --force`.
 
 Before each deploy, the daemon reloads the config path it was started with.
 Compatible process and lifecycle changes apply to the new release and govern

package/docs/config.md

@@ -46,6 +46,7 @@ restart.
 | `application` | string | basename of the config file's directory | Names the app; used in the default control-socket path and the `ROLLBRIDGE_APPLICATION` env var. |
 | `control` | object | — | Control-socket settings (see below). |
 | `legacyTakeover` | object | unset | Optional matchers for `rollbridge predeploy-cleanup` to stop pre-Rollbridge supervisors during first handover (see below). |
+| `ownerRecovery` | object | unset | Durable guardian recovery and atomic incompatible owner replacement; requires `statePath` (see below). |
 | `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). |
@@ -90,7 +91,7 @@ release records; the deploy tool still owns on-disk release directories.
 
 ## `statePath`
 
-When set, the daemon persists a secret-safe state snapshot — the active and
+When set, the daemon persists a sanitized operational state snapshot — the active and
 draining releases, each managed process's recovery metadata (including pid),
 restart counters, and recent structured events — to this file (atomically, on
 changes and every few seconds). Process commands, working directories,
@@ -98,13 +99,13 @@ environment mappings, child command lines, and retained stdout/stderr are never
 persisted. They remain available from the live `status`, `logs`, and `events`
 APIs while the daemon is running. On a clean `shutdown` the file is removed.
 
-On the **next startup**, the daemon reads any leftover file and reports managed
-processes whose pids are still alive — likely orphans from a daemon that crashed
-without shutting down cleanly — in its log and event history, and in the
+Without `ownerRecovery`, the **next startup** reads any leftover file and reports
+managed processes whose pids are still alive — likely orphans from a daemon that
+crashed without shutting down cleanly — in its log/event history and the
 `orphans` array of [`rollbridge status`](cli.md#status). This is **advisory**:
-Rollbridge cannot re-adopt detached children, so it does not stop them
-automatically; the operator verifies and stops the leftovers. A recycled pid can
-be a false positive, so treat a report as a prompt to investigate. Use
+that mode cannot re-adopt detached children, so it does not stop them
+automatically. A recycled pid can be a false positive, so treat a report as a
+prompt to investigate. Use
 [`rollbridge recover`](cli.md#recover) to list and (with `--force`) stop those
 orphans after a crash.
 
@@ -114,6 +115,54 @@ statePath: "/var/lib/rollbridge/ticket-server.state.json"
 
 Leave `statePath` unset to disable persistence (the default).
 
+Set `ownerRecovery` to opt into same-authority process-exit recovery and atomic
+incompatible owner replacement:
+
+```js
+statePath: "/var/lib/rollbridge/ticket-server.state.json",
+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.
+
+For a responsive incompatible owner, `ensure-daemon` prepares the requested
+durable runtime, restores exact active and draining generation definitions from
+the authenticated guardian, starts the candidate listeners, and then commits a
+single fenced guardian/control-socket handoff. Config identity, process topology,
+control path, and package/runtime identity may change; `statePath` remains the
+unchanged transaction anchor. Failures before commit leave the old owner serving.
+After commit, drains resume under their original release configs and never block
+the command. A monotonic guardian revision rejects a stale candidate if owner
+state changes after prepare. Listener-owned HTTP/WebSocket counts remain fenced
+to their releases until the retired listener reports them drained, preventing a
+later deploy from stopping the connected process early. Compatible per-deploy
+config reloads remain unchanged.
+
+The first upgrade from an authenticated pre-replacement Rollbridge guardian and
+daemon uses an explicitly disruptive compatibility bridge because that legacy
+owner cannot transfer listeners on Node 20. Rollbridge attests the exact guardian
+and daemon processes, sockets, runtime/config authority, and durable process
+registrations before retiring the legacy listeners. Managed process PIDs and
+release state remain supervised, but live proxy/control connections may close.
+The resulting status includes `ownerTransition: {disruptive: true, mode:
+"legacy-first-upgrade", ...}`. The bridge only accepts the incumbent config
+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.
+
+Without `ownerRecovery`, `statePath` retains the advisory orphan behavior above.
+
 ## `legacyTakeover`
 
 `legacyTakeover` lets deploy scripts run `rollbridge predeploy-cleanup` during
@@ -206,10 +255,14 @@ range** so old and new instances can run at the same time:
   policy: "service",
   deployStrategy: "handoff",
   command: "npx velocious background-jobs-main",
+  lifecycle: {quietCommand: "appctl jobs-main-retire --pid $ROLLBRIDGE_PID"},
   port: {from: 7331, to: 7399}
 }
 ```
 
+The `appctl` command is illustrative; the application must provide a reviewed
+equivalent that quiesces admission without terminating jobs-main.
+
 Reference it from same-release processes with `{{ports.background-jobs-main}}`.
 During a deploy, old workers keep the old port and new workers get the new port.
 For background jobs, the required compliant architecture makes the handoff
@@ -218,14 +271,14 @@ retirement must quiesce the old jobs-main's scheduling, dispatch, and new worker
 handoffs while keeping it with its workers until their accepted work settles.
 Workers are not adopted by the new service.
 
-That immediate old-main quiescence is **required future compliance behavior**,
-not current `deployStrategy: "handoff"` behavior. Today the release group starts
-`stop()` for `nonBlockingDrain` companions at retirement but sends no retirement
-or quiescence notice to the handoff service. It waits for the connection drain,
-stops other dependent processes, waits for the non-blocking companion stops, and
-only then stops the handoff service. Consequently, old and new jobs-main
-instances can overlap scheduling and dispatch ownership. Do not treat the
-configuration above alone as compliance with the background-jobs contract.
+Configure `lifecycle.quietCommand` on the handoff service to stop schedules,
+dispatch, and new handoffs without exiting. Immediately after activation,
+Rollbridge quiesces it with `nonBlockingDrain` companions, then returns without
+waiting for their drain. A failed hook leaves the generation alive, records
+`retirementError`, and emits `release retirement quiescence failed`. Durable
+same-authority recovery and guardian-fenced incompatible
+config/control-socket/package/runtime replacement are available with
+`ownerRecovery`.
 
 ### `processes[].lifecycle`
 
@@ -276,9 +329,9 @@ proxied process (a job worker on a shared queue). Rollbridge starts that
 companion's configured stop sequence **as soon as the release is retired**, in
 parallel with the connection drain, rather than after it. Its quiet command or
 signal must make the worker stop accepting new handoffs. The asynchronous
-release drain continues after the deploy response. As described above, current
-Rollbridge does not simultaneously quiesce the handoff service, so this setting
-alone does not prevent overlapping jobs-main scheduling or dispatch ownership.
+release drain continues after the deploy response. Rollbridge simultaneously
+quiesces same-release handoff services, so an old main stops new dispatch while
+remaining available to its old workers.
 
 ```js
 {id: "worker", policy: "companion", command: "…", nonBlockingDrain: true, stopSignal: "SIGINT", gracefulStopMs: "indefinite"}

package/docs/logging.md

@@ -40,9 +40,14 @@ When `statePath` is configured, its recovery snapshot is intentionally not a
 log archive: process commands, environment mappings, child command lines, and
 captured stdout/stderr are excluded. Use the live APIs above or the configured
 daemon log for those diagnostics, and protect that log according to the
-sensitivity of application output.
-
-Both are cleared when the daemon restarts; the log file persists.
+sensitivity of application output. With `ownerRecovery`, the mode-`0600`
+snapshot also contains the private guardian capability and its directory must be
+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.
 
 ## Rotation
 

package/docs/tensorbuzz-runbook.md

@@ -69,12 +69,13 @@ paths, and process references. Do not treat them as generic orphans to force-sto
 merely because a supervisor restarted. Cleanup becomes eligible only after the
 last retained process exits.
 
-Current Rollbridge does not yet meet those recovery and owner-handoff
-requirements. Its non-blocking release drains last only for the current daemon's
-lifetime; after restart it reports surviving PIDs as advisory, non-adoptable
-orphans, and forced recovery stops them. `--takeover-owner` quiesces and starts
-asynchronous stops for every managed process instead of transferring retained
-generations.
+Rollbridge meets the same-authority daemon-exit portion when `ownerRecovery` is
+configured: its guardian retains provenanced processes and a replacement
+reconstructs concurrent generations, endpoints, and `releaseReferences`.
+With the same `statePath`, `ensure-daemon` also performs guardian-fenced
+incompatible config/control-socket/package/runtime replacement without stopping
+those generations. Without that opt-in, surviving PIDs remain advisory orphans.
+`--takeover-owner` remains a separate destructive migration path.
 
 ## Operator checks
 

package/docs/troubleshooting.md

@@ -6,18 +6,30 @@
 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
+**Cause.** A daemon already owns the stable proxy/control socket, but Rollbridge
+cannot authenticate and attest an allowed owner transition.
+
+**Fix.** With `ownerRecovery`, a genuine pre-owner-replacement Rollbridge daemon
+and guardian can cross the documented one-time disruptive bridge automatically.
+Its existing proxy/control connections may close; successful status reports
+`ownerTransition.mode: "legacy-first-upgrade"`. Keep the incumbent config
+identity unchanged for that first invocation, then apply config/socket changes
+through the now-atomic replacement protocol. Do not treat arbitrary `Unknown
+command`, authentication, transport, malformed-response, or identity errors as
+legacy evidence: those intentionally fail closed and require repairing the
+reported authority or local socket/state problem. Without `ownerRecovery`, plan
+an explicit supervised restart during a safe handoff. 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.
 
+If startup instead reports `Rollbridge daemon candidate <pid> exited before
+readiness`, the ensuring CLI observed that exact child exit before it could
+attest status. The diagnostic includes the exit code or signal and spawned
+arguments. Inspect the configured `--daemon-log-path` for that PID's startup
+failure; this is distinct from a control-socket readiness timeout.
+
 Start with these three commands — they diagnose most problems without guessing:
 
 - `rollbridge validate` — config errors, with an example fix for each.
@@ -123,7 +135,11 @@ 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.
 
-Reporting release references to Rampway and pinning release directories against
-on-disk cleanup are required future behavior, not implemented today. Current
-Rollbridge `status` and `releaseRetention` govern only its in-memory release
-records and do not fence Rampway cleanup.
+`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
+`retirementError` is set,
+inspect the quiet-hook events. Rollbridge deliberately leaves that generation
+alive rather than signaling arbitrary PIDs or continuing its stop sequence.