rollbridge 0.1.2 → 0.1.4

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,22 @@ 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 `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 +124,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 +133,111 @@ 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/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 +246,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 +276,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,6 +330,19 @@ 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
@@ -246,6 +407,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 +416,7 @@ Maintainers can publish a patch release from the latest default branch:
 ```bash
 npm run release:patch
 ```
+
+## License
+
+Rollbridge is released under the [MIT License](LICENSE).

package/TODO.md

@@ -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,14 +71,14 @@ 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.
@@ -83,15 +86,15 @@ This roadmap tracks planned Rollbridge features and documentation. Rollbridge sh
 
 ## 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 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,151 @@
+# 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.
+
+## `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.

package/docs/config.md

@@ -0,0 +1,128 @@
+# Config reference
+
+A Rollbridge config is a JavaScript module that `export default`s a config
+object (or a sync/async function returning one). When `--config` is omitted,
+the CLI loads `rollbridge.js` from the working directory. Run
+`rollbridge validate` to check a config without starting the daemon.
+
+```js
+// rollbridge.js
+export default {
+  application: "ticket-server",
+  control: {path: "/tmp/rollbridge-ticket-server.sock"},
+  proxy: {host: "127.0.0.1", port: 8182},
+  processes: [
+    {id: "web", policy: "proxied", cwd: "{{releasePath}}", command: "npx velocious server --port {{port}}", port: {from: 18182, to: 18299}, health: {path: "/ping"}}
+  ]
+}
+```
+
+## Top-level fields
+
+| Field | Type | Default | Description |
+| --- | --- | --- | --- |
+| `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). |
+| `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). |
+
+## `control`
+
+| Field | Type | Default | Description |
+| --- | --- | --- | --- |
+| `control.path` | string | `/tmp/rollbridge-<application>.sock` | Unix domain socket the CLI uses to talk to the daemon. |
+| `control.mode` | octal string (e.g. `"660"`) or octal number (`0o660`) | unset | `chmod` applied to the socket after it binds, to share it with a deploy group. When unset, the daemon umask applies. |
+
+## `proxy`
+
+| Field | Type | Default | Description |
+| --- | --- | --- | --- |
+| `proxy.host` | string | `"127.0.0.1"` | Interface the stable proxy binds. |
+| `proxy.port` | number | `8182` | Stable port Nginx (or another front end) points at. |
+| `proxy.upstreamHost` | string | `proxy.host`, or `"127.0.0.1"` when `proxy.host` is `0.0.0.0`/`::` | Host Rollbridge uses for release health checks and proxy targets. |
+| `proxy.healthPath` | string | `"/ping"` | Default health-check path for proxied processes. |
+| `proxy.healthTimeoutMs` | number | `30000` | Default health-check timeout for proxied processes. |
+| `proxy.drainTimeoutMs` | number | `60000` | How long to drain open connections from a retired release before stopping it. |
+| `proxy.forceStopTimeoutMs` | number | `10000` | Default per-process graceful-stop timeout (`SIGTERM`, then `SIGKILL`). |
+
+## `releaseRetention`
+
+| Field | Type | Default | Description |
+| --- | --- | --- | --- |
+| `releaseRetention.keep` | non-negative integer | `10` | Number of most-recent **stopped** releases the daemon keeps in memory and reports in `status`. |
+| `releaseRetention.maxAgeMs` | non-negative number | `0` (disabled) | Also prune stopped releases older than this many milliseconds. |
+
+Active and draining releases are never pruned. This governs Rollbridge's own
+release records; the deploy tool still owns on-disk release directories.
+
+## `processes[]`
+
+| Field | Type | Default | Description |
+| --- | --- | --- | --- |
+| `id` | string | **required** | Unique identifier. Appears in `status`, logs, and `ROLLBRIDGE_*` env vars. |
+| `policy` | `"proxied"` \| `"companion"` \| `"singleton"` \| `"service"` | `"companion"` | Lifecycle policy (see [README → Process Policies](../README.md#process-policies)). Exactly one process must be `proxied`. |
+| `command` | string | **required** | Shell command to run (templated). |
+| `cwd` | string | the release path | Working directory (templated). |
+| `env` | object of string → string | `{}` | Extra environment variables (values templated). Merged over the injected `ROLLBRIDGE_*` vars. |
+| `port` | number or `{from, to}` | unset | Port (or range) allocated per release. **Required for the `proxied` process.** A plain number `n` means the fixed port `n` (`{from: n, to: n}`). |
+| `health` | object or `false` | enabled with defaults | Health check for the `proxied` process; set `false` to disable (see below). |
+| `gracefulStopMs` | number | `proxy.forceStopTimeoutMs` | `SIGTERM`→`SIGKILL` window for this process. |
+| `restartDelayMs` | number | `1000` | Delay before restarting this process after a crash. |
+| `outputLines` | positive integer | `50` | Recent stdout/stderr lines retained per process and reported by `status`/`logs`. |
+
+### `processes[].health`
+
+Only the `proxied` process is health-checked (before traffic switches to a new
+release). Set `health: false` to disable it.
+
+| Field | Type | Default | Description |
+| --- | --- | --- | --- |
+| `health.path` | string | `proxy.healthPath` | HTTP path probed on the process's port. |
+| `health.timeoutMs` | number | `proxy.healthTimeoutMs` | Total time to wait for the first healthy response. |
+| `health.intervalMs` | number | `250` | Delay between probes. |
+| `health.startDelayMs` | non-negative number | `0` | Wait this long after the process starts before the first probe (runs before the `timeoutMs` window). |
+
+## Template variables
+
+`command`, `cwd`, and `env` values support `{{...}}` placeholders, rendered when
+the process starts. Referencing a placeholder with no value fails the process
+start with a clear error.
+
+| Placeholder | Value |
+| --- | --- |
+| `{{application}}` | `application` |
+| `{{releaseId}}` | The deploy's release id. |
+| `{{releasePath}}` | The deploy's `--release-path`. |
+| `{{revision}}` | The deploy's `--revision` (falls back to the release id). |
+| `{{processId}}` | This process's `id`. |
+| `{{port}}` | The port allocated to this process. |
+| `{{ports.<id>}}` | The port allocated to another process. |
+| `{{proxy.host}}`, `{{proxy.port}}`, `{{proxy.upstreamHost}}` | The configured proxy bind host/port and upstream host. |
+| `{{env.<NAME>}}` | A variable from the daemon's own environment, e.g. `{{env.HOME}}`. |
+
+## Injected environment variables
+
+Rollbridge sets these in every managed process's environment (the process's own
+`env` is merged on top and can override them):
+
+| Variable | Value |
+| --- | --- |
+| `ROLLBRIDGE_APPLICATION` | `application` |
+| `ROLLBRIDGE_PROCESS_ID` | This process's `id`. |
+| `ROLLBRIDGE_RELEASE_ID` | The release id. |
+| `ROLLBRIDGE_RELEASE_PATH` | The release path. |
+| `ROLLBRIDGE_REVISION` | The revision (or release id). |
+| `ROLLBRIDGE_PORT` | This process's allocated port (only when it has one). |
+| `ROLLBRIDGE_<ID>_PORT` | Each process's allocated port, where `<ID>` is the process id uppercased with non-alphanumerics replaced by `_` (e.g. `background-jobs-main` → `ROLLBRIDGE_BACKGROUND_JOBS_MAIN_PORT`). |
+
+## Validation rules
+
+`rollbridge validate` reports all of these at once with an example fix:
+
+- Required `application` defaults are filled; `proxy` and `processes` must be present and well-typed.
+- Exactly one process must be `proxied`, and the `proxied` process must define a `port`.
+- Process `id`s must be unique.
+- `port` must be a positive port number or an ascending `{from, to}` range.
+- `control.mode` must be an octal mode between `0` and `0o777`.
+- `outputLines` and `releaseRetention.keep` must be positive/non-negative integers; `health.startDelayMs` and `releaseRetention.maxAgeMs` must be non-negative numbers.