rollbridge 0.1.5 → 0.1.7

package/README.md

@@ -84,7 +84,10 @@ more or fewer lines for chatty or quiet processes.
 Set `control.mode` to an octal permission string (for example `"660"`) to
 chmod the control socket after it binds. This restricts which users can send
 control commands — useful when several deploy users share a group. When unset,
-the socket keeps the default permissions from the daemon's umask.
+the socket keeps the default permissions from the daemon's umask. Pair it with
+`control.owner` and `control.group` (a numeric id or a user/group name) to
+`chown` the socket to a shared deploy group; names resolve via
+`/etc/passwd`/`/etc/group`, and the daemon must run as a user allowed to chown it.
 
 Set the proxied process's `health.startDelayMs` (default `0`) to wait that long
 after the process starts before the first health probe — like a readiness
@@ -103,6 +106,51 @@ restart. With no `restart` block, a crashed process keeps restarting after
 restart: {maxRestarts: 5, windowMs: 60000, backoffFactor: 2, maxDelayMs: 30000}
 ```
 
+Set a process's `memory` policy to supervise its resident memory (RSS) and
+gracefully restart it when it grows too large. `memory.limitBytes` is the RSS
+limit (measured across the whole process group, not just the wrapper);
+`memory.warnBytes` logs a warning before the limit; `memory.checkIntervalMs`
+(default `5000`) sets how often RSS is sampled. A memory restart is reported in
+`status` and recorded in `events` (a `process started` with `reason: "memory"`).
+See [`docs/config.md`](docs/config.md#processesmemory).
+
+```js
+memory: {limitBytes: 536870912, warnBytes: 402653184, checkIntervalMs: 5000}
+```
+
+Set a process's `stopSignal` (default `"SIGTERM"`) to the signal it quiets on, so
+a worker finishes its in-flight work before exiting. Rollbridge sends `stopSignal`
+to gracefully stop the process and `SIGKILL`s it only if it hasn't exited within
+`gracefulStopMs`. For example, a job worker that drains on `SIGINT`:
+
+```js
+{id: "worker", policy: "companion", command: "…", stopSignal: "SIGINT", gracefulStopMs: 60000}
+```
+
+Set `replicas` on a port-less `companion` to run a pool of identical workers.
+Each instance runs as `<id>#<index>` (`worker#0`, `worker#1`, …) — visible in
+`status` and targetable by `rollbridge restart` (base id for all, `worker#0` for
+one) — and gets `{{replicaIndex}}`/`{{replicaCount}}` and
+`ROLLBRIDGE_REPLICA_INDEX`/`_COUNT` so each instance can pick a distinct shard or
+queue. See [`docs/config.md`](docs/config.md#processesreplicas).
+
+```js
+{id: "worker", policy: "companion", command: "npx velocious background-jobs-worker", replicas: 4}
+```
+
+For workers that quiesce or drain via a command, set a `lifecycle` block —
+Rollbridge runs `quietCommand`, then drains (`drainCommand`/`drainTimeoutMs`),
+then `stopCommand`/`stopSignal`, then `SIGKILL` after `gracefulStopMs` when
+gracefully stopping the process. Each hook is bounded so it can't wedge a stop.
+
+Set `nonBlockingDrain: true` on a worker companion to start its graceful stop the
+moment its release is retired — in parallel with the proxied connection drain,
+not after it — so new workers handle new work while the old workers finish theirs.
+
+See [`docs/workers.md`](docs/workers.md) for the full safe background-job worker
+deployment pattern — companion policy, `replicas`, and finishing in-flight jobs
+on deploy with `stopSignal`/`lifecycle` + `gracefulStopMs`.
+
 Set `releaseRetention` to bound how many stopped (drained) releases the daemon
 keeps in memory and reports in `status`. `keep` (default `10`) retains the most
 recent stopped releases; `maxAgeMs` (default `0`, disabled) also prunes stopped
@@ -114,6 +162,32 @@ owns cleaning up on-disk release directories.
 releaseRetention: {keep: 5, maxAgeMs: 86400000}
 ```
 
+Set `statePath` to have the daemon persist its state to a file (active/draining
+releases, process pids, counters, recent events). On the next startup it 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
+`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).
+
+```js
+statePath: "/var/lib/rollbridge/ticket-server.state.json"
+```
+
+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
+Rollbridge release is running.
+
+```js
+legacyTakeover: {
+  screens: ["ticket-server"],
+  processes: [
+    {name: "legacy web", includes: ["/home/dev/ticket-server/", "velocious server", "--port 8082"]}
+  ]
+}
+```
+
 A function export receives no arguments and lets you build the config at load
 time:
 
@@ -143,7 +217,10 @@ 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
-`examples/tensorbuzz.com.js` for the current TensorBuzz backend deployment.
+`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
+operations).
 
 See [`docs/velocious.md`](docs/velocious.md) for a Velocious deployment guide —
 how Beacon, background-jobs-main, background-jobs-worker, and the web process map
@@ -348,8 +425,12 @@ rollbridge status --config rollbridge.js
 
 `status` reports each managed process's `state`, `pid`, recent `logs`, last
 `exitCode`/`exitSignal`, and — per process — its automatic-restart count
-(`restarts`), last start time (`startedAt`), and current `uptimeMs` while
-running.
+(`restarts`), last start time (`startedAt`), current `uptimeMs` while running,
+and why it last started (`lastStartReason`: `deploy`, `crash`, `manual`, or
+`memory`). The same reason appears on each `process started` entry in
+`rollbridge events`. For memory-supervised processes it also reports current
+`rssBytes`, `memoryRestarts`, `lastMemoryRestartAt`, and `children` (the sampled
+process tree — each group member's `pid`, `command`, and `rssBytes`).
 
 Print the recent captured stdout/stderr per process (a one-shot snapshot of the
 retained `outputLines`, not a live stream):
@@ -359,12 +440,31 @@ rollbridge logs --config rollbridge.js
 rollbridge logs --config rollbridge.js --process web
 ```
 
+Print the daemon's recent structured event history — deploys, traffic switches,
+release stops, process crashes/restarts, and failed commands (the most recent
+1000 events, in memory):
+
+```bash
+rollbridge events --config rollbridge.js
+rollbridge events --config rollbridge.js --limit 20
+```
+
 Stop the active release:
 
 ```bash
 rollbridge stop --config rollbridge.js
 ```
 
+Roll back to a previous release — re-starts it, health-checks it, and switches
+traffic back (defaults to the most recently retired release; a failed rollback
+leaves the current release active). Rollback manages processes only, not
+database migrations:
+
+```bash
+rollbridge rollback --config rollbridge.js                  # the previous release
+rollbridge rollback --config rollbridge.js --release-id v3
+```
+
 Restart non-proxied processes in place — all of them, one by id, or a policy
 group (the proxied process is never restarted; use `deploy` for that):
 
@@ -380,6 +480,20 @@ Shut down the daemon and managed processes:
 rollbridge shutdown --config rollbridge.js
 ```
 
+Prepare a first Rollbridge deploy by recovering Rollbridge-managed orphans and
+stopping configured legacy processes:
+
+```bash
+rollbridge predeploy-cleanup --config rollbridge.js --release-path /srv/app/current
+```
+
+Enable shell completion (bash or zsh) for command names and option flags:
+
+```bash
+source <(rollbridge completion bash)   # add to ~/.bashrc
+source <(rollbridge completion zsh)    # add to ~/.zshrc
+```
+
 ## Nginx
 
 Nginx should proxy to Rollbridge, not directly to Velocious:
@@ -432,6 +546,10 @@ The daemon is long-lived and survives deploys. **Deploy with
 release paths are passed per deploy. Use `command -v rollbridge` to find the
 absolute CLI path for `ExecStart`.
 
+See [`docs/logging.md`](docs/logging.md) for where the daemon's JSON logs go
+(stdout / journald / the `--daemon-log-path` file) and how to rotate them — the
+daemon holds its log file open, so logrotate needs `copytruncate`.
+
 ## Deployment Notes
 
 Run migrations before `rollbridge deploy`, and keep migrations backwards-compatible while old and new web releases overlap. For stable local brokers such as Velocious Beacon or `background-jobs-main`, use `service` when the process should survive deploys and restart from the latest successful release if it crashes.
@@ -450,6 +568,9 @@ The release script owns the package version bump, lockfile update, default-branc
 commit, push, and npm publish. Do not run `npm version` manually before running
 it.
 
+See [`docs/releasing.md`](docs/releasing.md) for the maintainer release checklist
+— the pre-flight checks before `npm run release:patch` and what to verify after.
+
 ## License
 
 Rollbridge is released under the [MIT License](LICENSE).

package/TODO.md

@@ -19,57 +19,58 @@ This roadmap tracks planned Rollbridge features and documentation. Rollbridge sh
 
 ## Major Features
 
-- [ ] Memory supervision.
-  - [ ] Add per-process memory config with an RSS limit, check interval, warning threshold, and restart policy.
-  - [ ] Measure the managed process tree, not only the shell wrapper PID.
-  - [ ] Report memory stats and last memory-triggered restart in `status`.
-  - [ ] Restart memory-heavy workers gracefully when possible, with a forced stop timeout.
-  - [ ] Add tests with a fixture process that allocates memory above the configured limit.
-- [ ] Worker auto-restart and restart policy controls.
+- [x] Memory supervision.
+  - [x] Add per-process memory config with an RSS limit, check interval, warning threshold, and restart policy.
+  - [x] Measure the managed process tree, not only the shell wrapper PID. (Sums RSS across the process group via `/proc`.)
+  - [x] Report memory stats and last memory-triggered restart in `status`.
+  - [x] Restart memory-heavy workers gracefully when possible, with a forced stop timeout.
+  - [x] Add tests with a fixture process that allocates memory above the configured limit.
+- [x] Worker auto-restart and restart policy controls.
   - [x] Add config for max restarts, restart window, exponential backoff, and disabled restart behavior (per-process `restart` policy).
-  - [ ] Distinguish crash restarts, deploy replacements, manual restarts, and memory restarts in status/events.
+  - [x] Distinguish crash restarts, deploy replacements, manual restarts, and memory restarts in status/events. (Per-process `lastStartReason` + a `reason` on the `process started` event; the `memory` reason is wired and fires once memory supervision restarts a process.)
   - [x] Add a `restart` CLI command for a single process, a policy group, or all non-proxied workers.
-  - [ ] Keep restart behavior safe for job workers by using lifecycle hooks before termination.
-- [ ] Graceful job-worker lifecycle.
-  - [ ] Add generic lifecycle hooks such as `quietCommand`, `drainCommand`, `drainTimeoutMs`, and `stopCommand`.
-  - [ ] Support signal-only lifecycle steps for workers that can quiet on a Unix signal.
-  - [ ] Add a non-blocking drain mode so new workers can start while old workers finish running jobs.
-  - [ ] Document a Velocious background-jobs-worker recipe once the lifecycle contract is implemented.
-- [ ] Replicas and stable worker indexes.
-  - [ ] Allow one process config to start multiple replicas.
-  - [ ] Expose `ROLLBRIDGE_REPLICA_INDEX`, replica count, and per-replica template context.
-  - [ ] Restart or stop one replica without affecting the rest.
-  - [ ] Preserve readable status output for replica groups.
-- [ ] Persistent daemon state and recovery.
-  - [ ] Persist active release, draining releases, process metadata, counters, and recent events.
-  - [ ] Reconnect status to still-running child processes after daemon restart where possible.
-  - [ ] Detect and report orphaned Rollbridge-managed processes.
-  - [ ] Add a recovery mode for safe startup after daemon crash or machine reboot.
-- [ ] Rollback support.
-  - [ ] Keep enough release metadata to switch traffic back to a previous healthy release.
-  - [ ] Add a `rollback` CLI command that health-checks the target before switching.
-  - [ ] Define how rollback interacts with singleton workers and draining releases.
-  - [ ] Document migration constraints for rollback.
-- [ ] Observability and diagnostics.
-  - [ ] Add structured event history for deploys, switches, stops, crashes, memory restarts, and failed commands.
+  - [x] Keep restart behavior safe for job workers by using lifecycle hooks before termination. (Manual restart, memory restart, and deploy-drain stops all run the `lifecycle` hooks via `stop()`.)
+- [x] Graceful job-worker lifecycle.
+  - [x] Add generic lifecycle hooks such as `quietCommand`, `drainCommand`, `drainTimeoutMs`, and `stopCommand` (per-process `lifecycle`).
+  - [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 new workers can start while old workers finish running jobs (per-process `nonBlockingDrain`; drains the worker in parallel with the connection drain).
+  - [x] Document a Velocious background-jobs-worker recipe once the lifecycle contract is implemented (`docs/velocious.md` → Worker recipe).
+- [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}}`).
+  - [x] Restart or stop one replica without affecting the rest (`rollbridge restart --process worker#0`).
+  - [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] 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.
+  - [x] Keep enough release metadata to switch traffic back to a previous healthy release.
+  - [x] Add a `rollback` CLI command that health-checks the target before switching.
+  - [x] Define how rollback interacts with singleton workers and draining releases. (Reuses the deploy flow: replaces singletons and drains the current release.)
+  - [x] Document migration constraints for rollback.
+- [x] Observability and diagnostics.
+  - [x] Add structured event history for deploys, switches, stops, crashes, memory restarts, and failed commands. (In-memory `EventLog` tapping the daemon logger; memory-restart events populate once memory supervision logs them.)
   - [x] Add restart counters and uptime to status (exit reasons already reported via `exitCode`/`exitSignal`/`state`).
-  - [ ] Add memory stats and child-process-tree details to status (with memory supervision).
+  - [x] Add memory stats and child-process-tree details to status (with memory supervision). (`rssBytes`/`memoryRestarts`/`lastMemoryRestartAt` plus `children`: the sampled process tree with each member's pid, command, and RSS.)
   - [x] Add a `logs` CLI command (recent per-process output from status).
-  - [ ] Add an `events` CLI command (after structured event history lands).
-  - [ ] Add optional file logging with rotation guidance.
+  - [x] Add an `events` CLI command (after structured event history lands).
+  - [x] Add optional file logging with rotation guidance (`docs/logging.md`; daemon log file via `--daemon-log-path`, logrotate `copytruncate`).
   - [x] Add machine-readable JSON output for all CLI commands (data commands print JSON; `validate`/`doctor`/`logs` take `--json`).
-- [ ] Config validation and doctoring.
+- [x] Config validation and doctoring.
   - [x] Add `validate` to parse config and report all config errors without starting the daemon.
   - [x] Add `doctor` to check config validity, control socket reachability, proxy port availability, and control-socket directory writability.
-  - [ ] Extend `doctor` with process-command, release-path, and log/state-path checks once those are resolvable (rendered templates, persisted state).
+  - [x] Extend `doctor` with state-path checks: state-path directory writability and orphaned-process reporting from a prior state file.
+  - [x] Extend `doctor` with process-command and release-path checks once those are resolvable (they need per-release rendered templates, which only exist at deploy time). (`rollbridge doctor --release-path <path>` renders each process's command/cwd/env against that release and checks the release directory, template resolvability, and rendered working directories; uses representative ports and replica index 0.)
   - [x] Validate duplicate process IDs, missing ports on proxied processes, invalid ranges, and the single-proxied-process policy rule.
-  - [ ] Validate unsupported lifecycle-hook combinations once worker lifecycle hooks land.
+  - [x] Validate unsupported lifecycle-hook combinations once worker lifecycle hooks land. (`lifecycle.drainCommand` requires a positive `drainTimeoutMs`; `nonBlockingDrain` is companion-only; a `lifecycle.stopCommand` may not be combined with a custom `stopSignal`, since the command runs instead of the signal.)
   - [x] Include example fixes in validation output.
 
 ## Minor Features
 
 - [x] Add a control-socket permission option (`control.mode`) for shared deploy users.
-- [ ] Add control-socket owner/group options for shared deploy users (needs name-to-id resolution).
+- [x] Add control-socket owner/group options for shared deploy users (`control.owner`/`control.group`, numeric id or name resolved via `/etc/passwd`/`/etc/group`).
 - [x] Make stale control socket diagnostics clearer when another daemon is still alive.
 - [x] Add old-release cleanup policies by age, count, and stopped state (`releaseRetention`).
 - [x] Add port allocation diagnostics when a range is exhausted.
@@ -77,7 +78,7 @@ This roadmap tracks planned Rollbridge features and documentation. Rollbridge sh
 - [x] Add process output retention config instead of a fixed recent-log count.
 - [x] Add environment variable interpolation from the daemon environment.
 - [x] Add `--config` default lookup resolving to `rollbridge.js` when no path is given.
-- [ ] Add shell completion generation for common shells.
+- [x] Add shell completion generation for common shells (`rollbridge completion bash|zsh`).
 - [x] Add npm package metadata such as repository, license, bugs, and homepage.
 - [x] Add systemd service examples for the Rollbridge daemon.
 - [x] Add tests for malformed control socket JSON and unknown control commands.
@@ -89,12 +90,13 @@ This roadmap tracks planned Rollbridge features and documentation. Rollbridge sh
 - [x] Write a full config reference covering every field, default, and template variable (`docs/config.md`).
 - [x] Write a CLI reference for `daemon`, `ensure-daemon`, `deploy`, `status`, `stop`, `shutdown`, and future commands (`docs/cli.md`).
 - [x] Expand process policy docs with deployment examples for `proxied`, `companion`, `singleton`, and `service`.
-- [ ] Document memory checks and auto-restart behavior after the feature lands.
-- [ ] Document worker lifecycle hooks and safe background-job deployment patterns after the feature lands.
+- [x] Document memory checks and auto-restart behavior after the feature lands (`docs/config.md` → `processes[].memory`).
+- [x] Document safe background-job deployment patterns (`docs/workers.md`: companion + `replicas` + `stopSignal` + `gracefulStopMs`, old/new worker overlap).
+- [x] Document worker lifecycle hooks (`docs/config.md` → `processes[].lifecycle`, `docs/workers.md`).
 - [x] Add a Velocious deployment guide with Beacon, background-jobs-main, background-jobs-worker, and web process examples (`docs/velocious.md`).
 - [x] Add an Nginx guide with WebSocket headers, timeouts, and common failure modes (`docs/nginx.md`).
 - [x] Add deploy-tool recipes that call Rollbridge CLI commands directly (`docs/deploy-recipes.md`).
 - [x] Add a Capistrano recipe showing shell commands only; do not add a Capistrano plugin or Rollbridge-specific Capistrano tasks (`docs/deploy-recipes.md`).
-- [ ] Add a TensorBuzz-specific runbook for current production ports, external services, deploy ordering, and rollback constraints.
+- [x] Add a TensorBuzz-specific runbook for current production ports, external services, deploy ordering, and rollback constraints (`docs/tensorbuzz-runbook.md`).
 - [x] Add troubleshooting docs for health-check failures, port conflicts, stale sockets, crash loops, and stuck draining releases (`docs/troubleshooting.md`).
-- [ ] Add a release checklist for maintainers using `npm run release:patch`.
+- [x] Add a release checklist for maintainers using `npm run release:patch` (`docs/releasing.md`).

package/docs/cli.md

@@ -46,7 +46,8 @@ already accepting commands, waits until it responds, then prints the daemon
 status JSON. Idempotent — safe to call before every deploy.
 
 - `--daemon-log-path <path>` — file the detached daemon's stdout/stderr is
-  appended to. Default: `/tmp/rollbridge-<application>.log`.
+  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-start-timeout-ms <ms>` — how long to wait for the daemon to accept
@@ -79,6 +80,35 @@ active and the command errors.
 - `--ensure-daemon` — start the daemon first if it isn't running (honors the
   same `--daemon-*` options as `ensure-daemon`).
 
+## `rollback`
+
+```
+rollbridge rollback [--config <path>] [--release-id <id>]
+```
+
+Rolls back to a previously-active release by re-running the deploy flow on its
+retained metadata: it re-starts that release, health-checks the proxied process,
+switches traffic, replaces singletons, and drains the current release — exactly
+like a deploy. With no `--release-id`, it targets the **most recently retired**
+release (the one active just before the current). Prints the same
+`{"activeReleaseId", "previousReleaseId"}` result as `deploy`.
+
+Because rollback reuses the deploy flow, a failed rollback (the target won't
+start or health-check) leaves the current release active and errors — it never
+takes the site down. Singletons are replaced (old stopped, then the target's
+started) and the current release is drained, just like any deploy.
+
+Errors when there is no previous release, the `--release-id` is not a retained
+release, or the target is already active. Only releases Rollbridge still retains
+(see [`releaseRetention`](config.md#releaseretention)) can be rolled back to.
+
+**Migration constraints.** Rollback only manages processes — it does **not**
+revert database migrations or other external state. The target release's on-disk
+directory must still exist, and its code must be compatible with the current
+schema. Keep migrations backwards-compatible (the same rule that lets old and
+new releases overlap during a deploy) so rolling code back to a retained release
+stays safe.
+
 ## `status`
 
 ```
@@ -87,8 +117,19 @@ rollbridge status [--config <path>]
 
 Prints the daemon status JSON: the active release id, the proxy address, and —
 per release, service, and singleton process — its `state`, `pid`, automatic
-`restarts`, `startedAt`, `uptimeMs`, last `exitCode`/`exitSignal`, and recent
-`logs`.
+`restarts`, `startedAt`, `uptimeMs`, last `exitCode`/`exitSignal`,
+`lastStartReason` (`deploy`, `crash`, `manual`, or `memory`), and recent `logs`.
+Memory-supervised processes also report `rssBytes`, `memoryRestarts`,
+`lastMemoryRestartAt`, and `children` (the process tree: each group member's
+`pid`, `command`, and `rssBytes`).
+
+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
+detached children kept running. It is empty in the normal case. Liveness is
+re-checked on each call, so the list clears itself as you stop the leftovers (see
+[`recover`](#recover)). These are reported only — the new daemon can't re-adopt
+them.
 
 ## `stop`
 
@@ -123,6 +164,49 @@ 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.
 
+## `predeploy-cleanup`
+
+```
+rollbridge predeploy-cleanup [--config <path>] [--release-path <path>]
+```
+
+Prepares a host for the first Rollbridge deploy. If a Rollbridge daemon already
+has an active release, the command exits without stopping anything. Otherwise it
+recovers Rollbridge-managed orphans from `statePath` and stops the legacy
+processes configured in [`legacyTakeover`](config.md#legacytakeover), then exits
+before `rollbridge deploy` starts the new daemon/proxy.
+
+When `--release-path` is provided, the command also restarts the existing daemon
+if the active release uses a different Rollbridge package version than the
+pending release. It also restarts the daemon when the active daemon's proxy host,
+port, or upstream host differs from the pending config.
+
+Use it immediately before `rollbridge deploy --ensure-daemon` when migrating an
+app from `screen`, `process_bot`, or another old supervisor to Rollbridge.
+
+## `recover`
+
+```
+rollbridge recover [--config <path>] [--force]
+```
+
+Cleans up orphaned managed processes left by a **crashed** daemon. It reads the
+persisted state ([`statePath`](config.md#statepath)) and finds managed processes
+whose pids are still alive. Without `--force` it only **lists** them (a dry run);
+with `--force` it stops each one's process group (`SIGTERM`, then `SIGKILL` after
+`proxy.forceStopTimeoutMs`) and clears the stale state file.
+
+Run it **before** restarting the daemon after a crash. It refuses to run while a
+daemon (or another process) holds the control socket — those pids belong to a
+live daemon, not a crash. A recycled pid can be a false positive, so review the
+dry-run list before using `--force`.
+
+If `--force` cannot stop some orphan (for example one now owned by another user,
+so it can't be signaled), that process is reported as still running, the state
+file is **kept** so you can investigate and re-run `recover`, and the command
+exits non-zero. Requires `statePath`; also exits non-zero when it is unset or a
+daemon is running.
+
 ## `shutdown`
 
 ```
@@ -146,15 +230,53 @@ issue with an example fix. Exits `1` when issues are found. With `--json`, print
 ## `doctor`
 
 ```
-rollbridge doctor [--config <path>] [--json]
+rollbridge doctor [--config <path>]
+                  [--release-path <path>]
+                  [--release-id <id>]
+                  [--revision <sha>]
+                  [--json]
 ```
 
 Validates the config, then probes the environment: whether a daemon already
 holds the control socket, whether the control socket's directory is writable,
-and whether the proxy port can be bound. Exits `1` when any check fails (so a
-green `doctor` means a fresh daemon can start). With `--json`, prints
+and whether the proxy port can be bound. When [`statePath`](config.md#statepath)
+is configured, it also checks that the state file's directory is writable and
+reports any **orphaned processes** — managed processes still alive in a prior
+state file, left by a daemon that didn't shut down cleanly (advisory; a recycled
+pid can be a false positive, so verify before stopping). Exits `1` when any check
+fails (so a green `doctor` means a fresh daemon can start). With `--json`, prints
 `{"checks": [{"name", "ok", "detail"}], "ok"}`.
 
+### Pre-flighting a release with `--release-path`
+
+Process commands, working directories, and env values are
+[templates](config.md#template-variables) (`{{releasePath}}`, `{{port}}`, …) that
+are only rendered at deploy time, against a specific release. Pass
+`--release-path <path>` to a **prepared release directory** to add deploy-time
+checks against it:
+
+- **release path** — the release directory exists.
+- **process templates** — every process's `command`, `cwd`, and `env` templates
+  resolve (no `{{…}}` references an undefined variable). Ports are rendered with
+  the low end of each process's configured range.
+- **process working directories** — each process's rendered `cwd` (defaulting to
+  the release path) exists.
+
+`--release-id` and `--revision` set `{{releaseId}}`/`{{revision}}` for rendering
+(defaulting the way `deploy` does: `--release-id` falls back to `--revision` or
+the release path's basename, and `--revision` falls back to `--release-id`). Run
+it as part of a deploy pipeline, after preparing the release and before
+`rollbridge deploy`, to catch a template typo or a missing directory before
+traffic is involved:
+
+```bash
+rollbridge doctor --config /etc/rollbridge/app.js --release-path /srv/app/releases/20260524
+```
+
+These checks render replica index `0` and use representative ports, so they
+catch template and path problems but not values that only exist once the daemon
+allocates real ports and spawns processes.
+
 ## `logs`
 
 ```
@@ -166,6 +288,44 @@ snapshot of each process's `outputLines`, not a live stream. `--process <id>`
 limits output to one process. With `--json`, prints
 `[{"id", "source", "logs": [{"at", "line", "stream"}]}]`.
 
+## `events`
+
+```
+rollbridge events [--config <path>] [--limit <count>] [--json]
+```
+
+Prints the daemon's recent structured event history — deploys (`deploy
+starting`, `traffic switched`, `deploy failed`), release stops (`release
+stopped`, `release drained`), process lifecycle (`process started` — with a
+`reason` of `deploy`, `crash`, `manual`, or `memory` — `process exited`,
+`memory limit exceeded`, `restart limit reached`, `process restart requested`),
+and failed control commands (`command failed`). Each event has a timestamp, a
+message, and a structured data payload. The daemon keeps the most recent 1000 events in
+memory (cleared on restart). `--limit <count>` shows only the most recent
+`count`. With `--json`, prints `[{"at", "message", "data"}]`.
+
+## `completion`
+
+```
+rollbridge completion <bash|zsh>
+```
+
+Prints a shell completion script to stdout, generated by introspecting the
+command set (so it never drifts from the real commands and options). It
+completes command names, each command's option flags, and falls back to file
+completion after an option that takes a value (bash). Enable it for the current
+session, or add the line to your shell startup file:
+
+```bash
+# bash (~/.bashrc)
+source <(rollbridge completion bash)
+
+# zsh (~/.zshrc)
+source <(rollbridge completion zsh)
+```
+
+An unsupported shell exits `1` with the list of supported shells.
+
 ## Exit codes
 
 - `0` — success.