rollbridge 0.1.2 → 0.1.5

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 kaspernj
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -37,6 +37,7 @@ export default {
   proxy: {
     host: "127.0.0.1",
     port: 8182,
+    upstreamHost: "127.0.0.1",
     healthPath: "/ping",
     healthTimeoutMs: 30000,
     drainTimeoutMs: 60000,
@@ -85,6 +86,34 @@ 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.
 
+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
+probe's initial delay, useful for apps with a known boot time. The delay runs
+before the `health.timeoutMs` window begins.
+
+Set a process's `restart` policy to control automatic restarts after a crash.
+`restart.maxRestarts` caps how many restarts are allowed within `restart.windowMs`
+before Rollbridge gives up and leaves the process `failed` (`maxRestarts: 0`
+disables restarts entirely), while `restart.backoffFactor` — with an optional
+`restart.maxDelayMs` cap — backs off the `restartDelayMs` delay on each successive
+restart. With no `restart` block, a crashed process keeps restarting after
+`restartDelayMs`, as before. See [`docs/config.md`](docs/config.md#processesrestart).
+
+```js
+restart: {maxRestarts: 5, windowMs: 60000, backoffFactor: 2, maxDelayMs: 30000}
+```
+
+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
+releases older than that many milliseconds. The active and draining releases are
+never pruned. This is Rollbridge's own release records — your deploy tool still
+owns cleaning up on-disk release directories.
+
+```js
+releaseRetention: {keep: 5, maxAgeMs: 86400000}
+```
+
 A function export receives no arguments and lets you build the config at load
 time:
 
@@ -107,7 +136,7 @@ rendered when the process starts:
 
 - `{{releasePath}}`, `{{releaseId}}`, `{{revision}}`, `{{application}}`, `{{processId}}`
 - `{{port}}` — the port allocated to this process; `{{ports.<id>}}` — another process's allocated port
-- `{{proxy.host}}`, `{{proxy.port}}`
+- `{{proxy.host}}`, `{{proxy.port}}`, `{{proxy.upstreamHost}}`
 - `{{env.<NAME>}}` — a variable from the daemon's own environment, e.g. `{{env.HOME}}`
 
 Referencing a placeholder with no value (including an unset `{{env.<NAME>}}`)
@@ -116,12 +145,115 @@ 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.
 
+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
+to Rollbridge policies, with startup ordering and deploy behavior.
+
+See [`docs/config.md`](docs/config.md) for the full config reference — every
+field, its default, validation rules, template variables, and the environment
+variables Rollbridge injects.
+
 ## Process Policies
 
-- `proxied`: the web/API process. Rollbridge forwards HTTP and WebSocket traffic to the active release and tracks connections for draining.
-- `companion`: a release-scoped support process. It starts with the release and stops after that release drains.
-- `singleton`: a one-at-a-time support process. Rollbridge stops the old singleton before starting the new one, so duplicate-unsafe schedulers or job dispatchers do not overlap.
-- `service`: a daemon-wide support process. Rollbridge starts it before release processes need it, leaves it running across deploys, and updates its restart template after a successful deploy.
+Every process declares a `policy` that controls its lifecycle. Pick one per
+process:
+
+| You need… | Use |
+| --- | --- |
+| The process that receives external HTTP/WebSocket traffic | `proxied` |
+| A per-release helper tied to the release lifecycle | `companion` |
+| Exactly one instance, never overlapping across deploys | `singleton` |
+| A long-lived shared broker that survives deploys | `service` |
+
+### `proxied`
+
+The web/API process — exactly one per config. Rollbridge forwards HTTP and
+WebSocket traffic to the active release's proxied process and tracks open
+connections so they can be drained on the next deploy. It must define a `port`
+range, is health-checked before traffic switches to a new release, and is
+auto-restarted while its release is active.
+
+```js
+{
+  id: "web",
+  policy: "proxied",
+  cwd: "{{releasePath}}",
+  command: "npx velocious server --host 127.0.0.1 --port {{port}}",
+  port: {from: 18182, to: 18299},
+  health: {path: "/ping", timeoutMs: 30000}
+}
+```
+
+### `companion`
+
+A release-scoped helper (for example a background worker bound to one release).
+It starts **before** the proxied process in the same release, so release-local
+dependencies are ready before the health check, and it is auto-restarted while
+its release is active. Each release gets its own companions; a release's
+companions stop when that release is drained and retired after a newer release
+takes over.
+
+```js
+{
+  id: "background-jobs-worker",
+  policy: "companion",
+  cwd: "{{releasePath}}",
+  command: "npx velocious background-jobs-worker",
+  gracefulStopMs: 60000
+}
+```
+
+### `singleton`
+
+A one-at-a-time helper for duplicate-unsafe schedulers or job dispatchers. After
+a new release becomes active, Rollbridge stops the old singleton and then starts
+the new one, so two copies never run at once. Use it when running the old and
+new copies simultaneously during a deploy would be unsafe.
+
+```js
+{
+  id: "scheduler",
+  policy: "singleton",
+  cwd: "{{releasePath}}",
+  command: "npx velocious scheduler"
+}
+```
+
+### `service`
+
+A daemon-wide broker that should outlive individual releases — for example
+Velocious Beacon or `background-jobs-main`. Rollbridge starts it once (before
+release processes that depend on it), keeps it running across deploys, and gives
+it a stable port that does not change between releases. After each successful
+deploy its restart template is refreshed to the latest release, so if it crashes
+it restarts from the newest good release. It keeps restarting until the daemon
+shuts down.
+
+```js
+{
+  id: "background-jobs-main",
+  policy: "service",
+  cwd: "{{releasePath}}",
+  command: "npx velocious background-jobs-main",
+  port: 7331
+}
+```
+
+### Deploy ordering
+
+On `rollbridge deploy`, Rollbridge:
+
+1. starts any `service` that is not already running;
+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. refreshes each `service`'s restart template to the new release;
+5. replaces `singleton`s (stops the old one, then starts the new one);
+6. drains the previous release's connections, then stops its `proxied` and
+   `companion` processes.
+
+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.
 
 ## Commands
 
@@ -130,6 +262,14 @@ Production-ready examples live in `examples/`, including
 explicitly, but `rollbridge validate` (or any command) works with no flag when a
 `rollbridge.js` is present.
 
+For machine-readable output, `deploy`, `status`, `stop`, `shutdown`, and
+`ensure-daemon` already print JSON, and `validate`, `doctor`, and `logs` accept
+a `--json` flag that switches their output to JSON (with the same exit codes),
+so deploy tooling can parse results.
+
+See [`docs/cli.md`](docs/cli.md) for the full per-command reference (every
+option, default, output shape, and exit code).
+
 Validate a config without starting the daemon:
 
 ```bash
@@ -152,6 +292,30 @@ Found 2 configuration issues in rollbridge.js:
    Fix: Give each process a unique id; "web" is used more than once.
 ```
 
+Check the environment before starting the daemon:
+
+```bash
+rollbridge doctor --config rollbridge.js
+```
+
+`doctor` validates the config and then probes the runtime environment, exiting
+non-zero if any check fails (so deploy tooling can gate on it):
+
+```text
+✓ config: valid: 4 processes, proxy on 127.0.0.1:8182
+✓ control socket: no daemon running; /tmp/rollbridge-ticket-server.sock is free to bind
+✓ control socket directory: /tmp is writable
+✓ proxy port: 127.0.0.1:8182 is available
+
+All checks passed.
+```
+
+A free control socket, a writable socket directory, and a bindable proxy port
+pass. Because `rollbridge daemon` cannot bind a socket or port that is already
+taken, doctor fails the relevant check when a Rollbridge daemon (or any other
+process) is already listening on the control socket or holding the proxy port —
+so a green `doctor` means a fresh daemon can actually start.
+
 Start the daemon:
 
 ```bash
@@ -182,12 +346,34 @@ Inspect state:
 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.
+
+Print the recent captured stdout/stderr per process (a one-shot snapshot of the
+retained `outputLines`, not a live stream):
+
+```bash
+rollbridge logs --config rollbridge.js
+rollbridge logs --config rollbridge.js --process web
+```
+
 Stop the active release:
 
 ```bash
 rollbridge stop --config rollbridge.js
 ```
 
+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):
+
+```bash
+rollbridge restart --config rollbridge.js                      # all non-proxied processes
+rollbridge restart --config rollbridge.js --process background-jobs-worker
+rollbridge restart --config rollbridge.js --policy companion
+```
+
 Shut down the daemon and managed processes:
 
 ```bash
@@ -210,6 +396,10 @@ location / {
 }
 ```
 
+See [`docs/nginx.md`](docs/nginx.md) for the full guide — WebSocket upgrade
+headers, timeouts for long-lived connections, forwarded headers, and common
+failure modes (502/503, dropped WebSockets).
+
 ## Running under systemd
 
 Run the long-lived daemon as a systemd service so it starts on boot and is
@@ -246,6 +436,8 @@ absolute CLI path for `ExecStart`.
 
 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.
 
+See [`docs/deploy-recipes.md`](docs/deploy-recipes.md) for ready-to-use shell, CI, and Capistrano recipes that drive Rollbridge through its CLI, and [`docs/troubleshooting.md`](docs/troubleshooting.md) for diagnosing health-check failures, port conflicts, stale sockets, crash loops, and stuck draining releases.
+
 ## Releasing
 
 Maintainers can publish a patch release from the latest default branch:
@@ -253,3 +445,11 @@ Maintainers can publish a patch release from the latest default branch:
 ```bash
 npm run release:patch
 ```
+
+The release script owns the package version bump, lockfile update, default-branch
+commit, push, and npm publish. Do not run `npm version` manually before running
+it.
+
+## License
+
+Rollbridge is released under the [MIT License](LICENSE).

package/TODO.md

@@ -26,9 +26,9 @@ This roadmap tracks planned Rollbridge features and documentation. Rollbridge sh
   - [ ] 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.
-  - [ ] Add config for max restarts, restart window, exponential backoff, and disabled restart behavior.
+  - [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.
-  - [ ] Add a `restart` CLI command for a single process, a policy group, or all non-proxied workers.
+  - [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`.
@@ -52,13 +52,16 @@ This roadmap tracks planned Rollbridge features and documentation. Rollbridge sh
   - [ ] Document migration constraints for rollback.
 - [ ] Observability and diagnostics.
   - [ ] Add structured event history for deploys, switches, stops, crashes, memory restarts, and failed commands.
-  - [ ] Add restart counters, uptime, exit reasons, memory stats, and child-process-tree details to status.
-  - [ ] Add `logs` and `events` CLI commands.
+  - [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 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.
-  - [ ] Add machine-readable JSON output flags for all CLI commands.
+  - [x] Add machine-readable JSON output for all CLI commands (data commands print JSON; `validate`/`doctor`/`logs` take `--json`).
 - [ ] Config validation and doctoring.
   - [x] Add `validate` to parse config and report all config errors without starting the daemon.
-  - [ ] Add `doctor` to check control socket reachability, proxy port availability, process commands, release path, and writable log/state paths.
+  - [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] 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] Include example fixes in validation output.
@@ -68,30 +71,30 @@ This roadmap tracks planned Rollbridge features and documentation. Rollbridge sh
 - [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] Make stale control socket diagnostics clearer when another daemon is still alive.
-- [ ] Add old-release cleanup policies by age, count, and stopped state.
+- [x] Add old-release cleanup policies by age, count, and stopped state (`releaseRetention`).
 - [x] Add port allocation diagnostics when a range is exhausted.
-- [ ] Add optional startup command timeout before health checks begin.
+- [x] Add an optional startup delay (`health.startDelayMs`) before health checks begin.
 - [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.
-- [ ] Add npm package metadata such as repository, license, bugs, and homepage.
+- [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.
-- [ ] Add tests for duplicate IDs and singleton replacement failure behavior.
+- [x] Add tests for duplicate IDs and singleton replacement failure behavior.
 - [x] Add tests for proxy behavior when the active release exits unexpectedly.
 
 ## Documentation TODO
 
-- [ ] Write a full config reference covering every field, default, and template variable.
-- [ ] Write a CLI reference for `daemon`, `ensure-daemon`, `deploy`, `status`, `stop`, `shutdown`, and future commands.
-- [ ] Expand process policy docs with deployment examples for `proxied`, `companion`, `singleton`, and `service`.
+- [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.
-- [ ] Add a Velocious deployment guide with Beacon, background-jobs-main, background-jobs-worker, and web process examples.
-- [ ] Add an Nginx guide with WebSocket headers, timeouts, and common failure modes.
-- [ ] Add deploy-tool recipes that call Rollbridge CLI commands directly.
-- [ ] Add a Capistrano recipe showing shell commands only; do not add a Capistrano plugin or Rollbridge-specific Capistrano tasks.
+- [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.
-- [ ] Add troubleshooting docs for health-check failures, port conflicts, stale sockets, crash loops, and stuck draining releases.
+- [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`.

package/docs/cli.md

@@ -0,0 +1,174 @@
+# Rollbridge CLI reference
+
+```
+rollbridge <command> [options]
+```
+
+This reference covers every current command. See the README for config and
+process-policy details.
+
+## Global behavior
+
+- **`-c, --config <path>`** is accepted by every command and is optional. When
+  omitted, Rollbridge loads `rollbridge.js` from the current directory (a
+  JavaScript module that `export default`s the config object or a function
+  returning it).
+- Commands that talk to a running daemon — `deploy`, `status`, `stop`,
+  `shutdown`, and `logs` — connect to the control socket (`control.path`). They
+  fail with an error if no daemon is listening; start one first with
+  `rollbridge daemon` or `rollbridge deploy --ensure-daemon`.
+- `validate`, `doctor`, and `logs` accept `--json` for machine-readable output.
+  `deploy`, `status`, `stop`, `shutdown`, and `ensure-daemon` always print JSON.
+
+## `daemon`
+
+```
+rollbridge daemon [--config <path>]
+```
+
+Runs the supervisor in the foreground: binds the stable proxy port and the
+control socket and stays running. On `SIGINT`/`SIGTERM` it stops its managed
+processes, closes the servers, removes the control socket, and exits `0`.
+Structured JSON log lines are written to stdout. Run it under a process manager
+such as systemd (see `examples/rollbridge.service`).
+
+## `ensure-daemon`
+
+```
+rollbridge ensure-daemon [--config <path>]
+                         [--daemon-log-path <path>]
+                         [--daemon-pid-path <path>]
+                         [--daemon-start-timeout-ms <ms>]
+```
+
+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.
+
+- `--daemon-log-path <path>` — file the detached daemon's stdout/stderr is
+  appended to. Default: `/tmp/rollbridge-<application>.log`.
+- `--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
+  control commands before failing. Default: `10000`.
+
+## `deploy`
+
+```
+rollbridge deploy --release-path <path>
+                  [--config <path>]
+                  [--release-id <id>]
+                  [--revision <sha>]
+                  [--ensure-daemon]
+                  [--daemon-log-path <path>]
+                  [--daemon-pid-path <path>]
+                  [--daemon-start-timeout-ms <ms>]
+```
+
+Starts the prepared release, health-checks the proxied process, switches new
+traffic to it, then drains and stops the previous release. Prints
+`{"status": "success", "activeReleaseId": "...", "previousReleaseId": "..."}`.
+If the new release fails to start or health-check, the previous release stays
+active and the command errors.
+
+- `--release-path <path>` (**required**) — path to the prepared release
+  directory; available to process templates as `{{releasePath}}`.
+- `--release-id <id>` — identifier for the release. Defaults to `--revision`,
+  or a timestamp when neither is given.
+- `--revision <sha>` — VCS revision; available as `{{revision}}`.
+- `--ensure-daemon` — start the daemon first if it isn't running (honors the
+  same `--daemon-*` options as `ensure-daemon`).
+
+## `status`
+
+```
+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`.
+
+## `stop`
+
+```
+rollbridge stop [--config <path>] [--release-id <id>]
+```
+
+Stops the active release (or the release named by `--release-id`) and prints the
+updated status JSON. With no active release, the proxy answers `503` until the
+next deploy.
+
+## `restart`
+
+```
+rollbridge restart [--config <path>] [--process <id>] [--policy <policy>]
+```
+
+Restarts **non-proxied** processes and prints `{"restarted": [<ids>]}`. Like
+`systemctl restart`, a running process is bounced (stop, then start) and a
+crashed or stopped one is revived — so this is also how you bring back a process
+that exhausted its `restart` budget (see [`config.md`](config.md#processesrestart)).
+Selectors:
+
+- no selector — restart every non-proxied process (companions, singletons, and services);
+- `--process <id>` — restart only that process;
+- `--policy <companion|singleton|service>` — restart only processes with that policy.
+
+The proxied process is never restarted in place — that would drop traffic.
+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.
+
+## `shutdown`
+
+```
+rollbridge shutdown [--config <path>]
+```
+
+Stops all managed processes (services, singletons, and releases), closes the
+proxy and control socket, removes the socket file, and prints
+`{"status": "success", "message": "shutdown"}`.
+
+## `validate`
+
+```
+rollbridge validate [--config <path>] [--json]
+```
+
+Parses and validates the config without starting the daemon, reporting every
+issue with an example fix. Exits `1` when issues are found. With `--json`, prints
+`{"config": {...} | null, "issues": [{"message", "fix"}], "path", "valid"}`.
+
+## `doctor`
+
+```
+rollbridge doctor [--config <path>] [--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
+`{"checks": [{"name", "ok", "detail"}], "ok"}`.
+
+## `logs`
+
+```
+rollbridge logs [--config <path>] [--process <id>] [--json]
+```
+
+Prints the recent stdout/stderr retained per managed process — a one-shot
+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"}]}]`.
+
+## Exit codes
+
+- `0` — success.
+- `1` — `validate`/`doctor` found problems, or `--config` could not be resolved.
+- non-zero (with an error message) — a daemon command could not reach the daemon,
+  or the daemon returned an error.