rollbridge 0.1.1 → 0.1.4

package/docs/deploy-recipes.md

@@ -0,0 +1,102 @@
+# Deploy-tool recipes
+
+Rollbridge is deploy-tool agnostic: it ships no plugins or tasks for any deploy
+tool. Whatever you use — a shell script, CI, or Capistrano — drives Rollbridge
+by **calling its CLI** (see [`cli.md`](cli.md)). The daemon is long-lived;
+deploys just hand it a prepared release path.
+
+The deploy contract is the same everywhere:
+
+1. Prepare the release directory (checkout, install dependencies, build assets).
+2. Run **backwards-compatible** migrations *before* switching traffic (the old
+   and new web releases overlap during the drain).
+3. Run `rollbridge deploy` — it starts the new release, health-checks the
+   proxied process, switches traffic, then drains and stops the old release.
+   It exits non-zero (leaving the previous release active) if the new release
+   fails to start or health-check, so your script should stop on a failed
+   deploy.
+
+Point `--config` at a stable, daemon-wide config file; release paths are passed
+per deploy. `rollbridge deploy --ensure-daemon` starts the daemon first if it
+isn't already running, so the recipes below work whether or not the daemon is
+already managed by systemd.
+
+## Shell script
+
+```bash
+#!/usr/bin/env bash
+set -euo pipefail
+
+app_dir=/srv/ticket-server
+config=/etc/rollbridge/rollbridge.js
+# Read the revision from the source repo (not the script's cwd, which may not be
+# a checkout under cron/systemd/CI).
+revision="$(git -C "$app_dir/repo" rev-parse HEAD)"
+release_path="$app_dir/releases/$(date -u +%Y%m%d%H%M%S)-$revision"
+
+# 1. Prepare the release.
+git clone --depth 1 "$app_dir/repo" "$release_path"
+(cd "$release_path" && npm ci && npm run build)
+
+# 2. Run backwards-compatible migrations before switching traffic.
+(cd "$release_path" && npx velocious db:migrate)
+
+# 3. Switch traffic (and start the daemon if needed). A non-zero exit here means
+#    the new release failed health checks and the previous one is still active;
+#    `set -e` aborts the script so the bad release is not promoted.
+rollbridge deploy \
+  --ensure-daemon \
+  --config "$config" \
+  --release-path "$release_path" \
+  --revision "$revision"
+```
+
+## CI
+
+In CI, build/test the release, then run the same `rollbridge deploy` over SSH
+on the target host (CI rarely runs the long-lived daemon itself):
+
+```bash
+# after the build/test job has produced a release at $RELEASE_PATH on the host
+ssh deploy@app.example.com \
+  "rollbridge deploy --ensure-daemon \
+     --config /etc/rollbridge/rollbridge.js \
+     --release-path '$RELEASE_PATH' \
+     --revision '$GIT_SHA'"
+```
+
+`rollbridge deploy` exits non-zero on a failed health check, which fails the CI
+step — no extra gating needed. Use `rollbridge validate --json` / `rollbridge
+doctor --json` earlier in the pipeline if you want to fail fast before building.
+
+## Capistrano
+
+Rollbridge ships **no Capistrano plugin or tasks** — you only run its CLI as a
+shell command from your own `deploy.rb`. Capistrano already uploads the release
+to `release_path`, so the deploy step is a single `execute` of the CLI:
+
+```ruby
+# config/deploy.rb — just a shell command; no Rollbridge-specific Capistrano code.
+after "deploy:publishing", "rollbridge:deploy"
+
+namespace :rollbridge do
+  task :deploy do
+    on roles(:app) do
+      within release_path do
+        execute :npx, "velocious", "db:migrate"
+      end
+      execute "rollbridge", "deploy",
+        "--ensure-daemon",
+        "--config", "/etc/rollbridge/rollbridge.js",
+        "--release-path", release_path,
+        "--revision", fetch(:current_revision)
+    end
+  end
+end
+```
+
+`execute` runs the command over SSH and raises if it exits non-zero, so a failed
+Rollbridge health check fails the Capistrano deploy. Keep Capistrano's own
+`linked_dirs`/`keep_releases` for on-disk release directories; Rollbridge only
+manages the running processes and its own in-memory release records (see
+`releaseRetention`).

package/docs/troubleshooting.md

@@ -0,0 +1,102 @@
+# Troubleshooting
+
+Start with these three commands — they diagnose most problems without guessing:
+
+- `rollbridge validate` — config errors, with an example fix for each.
+- `rollbridge doctor` — control socket reachability, socket-directory writability, and proxy-port availability before the daemon starts.
+- `rollbridge status` / `rollbridge logs` — live release/process state, restart counts, exit codes, connection counts, and recent process output.
+
+For scripting, `validate`, `doctor`, and `logs` accept a `--json` flag, and
+`status` already prints JSON — so every command's output is easy to parse.
+
+## Health-check failures
+
+**Symptom.** `rollbridge deploy` exits non-zero with:
+
+```
+Health check failed for http://127.0.0.1:18182/ping: HTTP 503
+```
+
+(the reason is `HTTP <status>` or a connection error such as `ECONNREFUSED`). The
+new release never went live; the previous release stays active.
+
+**Diagnose.** The new release's `proxied` process didn't return a healthy
+response in time. Check its output with `rollbridge logs --process <id>` and its
+state/`exitCode` with `rollbridge status`. Common causes: the app doesn't listen
+on the templated `{{port}}`, the `health.path` returns a non-2xx status, or the
+app boots slower than `health.timeoutMs`.
+
+**Fix.** Make the proxied command bind `{{port}}` and serve `health.path` with a
+2xx status. For slow boots, raise `health.timeoutMs` or set `health.startDelayMs`
+so probing begins after the app is up.
+
+## Port conflicts / exhausted ranges
+
+**Symptom.** A deploy fails with:
+
+```
+No available ports in range 18182-18299 (118 ports on 127.0.0.1): 0 reserved by this deploy, 118 already in use. Widen the port range, free a port, or check bind permissions.
+```
+
+**Diagnose.** The counts tell you which case it is:
+
+- **reserved by this deploy** high → the range is too small for the processes that share it.
+- **already in use** → another process (or an old release that has not finished draining) holds the ports.
+- **could not be bound (e.g. EACCES)** → permission problem, e.g. a privileged (`<1024`) port.
+
+`rollbridge doctor` reports whether the configured `proxy.port` is bindable.
+
+**Fix.** Widen the process's `port` range, free the conflicting port (`ss -ltnp`
+or `lsof -i :<port>` to find the holder), or avoid privileged ports / grant the
+needed capability.
+
+## Stale or busy control socket
+
+**Symptom.** `rollbridge daemon` (or `ensure-daemon`) errors with one of:
+
+```
+A Rollbridge daemon for application "ticket-server" is already running on /tmp/rollbridge-ticket-server.sock (active release: v3). Run "rollbridge status" to inspect it or "rollbridge shutdown" to stop it, or set a different control.path.
+The control socket /tmp/rollbridge-ticket-server.sock is already in use by another process. Stop that process or set a different control.path.
+```
+
+**Diagnose.** Run `rollbridge status` (does a daemon answer?) and `rollbridge
+doctor` (control-socket check). A leftover socket *file* with no live daemon
+behind it is removed automatically the next time the daemon starts — no action
+needed.
+
+**Fix.** If a Rollbridge daemon is already running, use it, or
+`rollbridge shutdown` before starting another. If a non-Rollbridge process owns
+the path, stop it or point `control.path` somewhere else.
+
+## Crash loops
+
+**Symptom.** `rollbridge status` shows a process with a climbing `restarts`
+count and a `state` that flips between `running` and `failed`, with repeated
+`process started` / `process exited` log lines.
+
+**Diagnose.** `rollbridge logs --process <id>` shows the crash output;
+`rollbridge status` shows `exitCode`, `exitSignal`, `restarts`, and `uptimeMs`
+(a tiny `uptimeMs` that keeps resetting is a fast crash loop). Crashed
+active-release and `service` processes auto-restart after `restartDelayMs`.
+
+**Fix.** Correct the command, environment, or dependency that makes the process
+exit; raise `restartDelayMs` to slow a tight loop. Note that a release which
+fails its health check never receives traffic, so a crash-looping proxied
+process in a *failed* deploy does not take the site down — the previous release
+stays active.
+
+## Stuck draining releases
+
+**Symptom.** Long after a deploy, `rollbridge status` still shows an old release
+in `state: "draining"` with non-zero `connections` (often `websocket`).
+
+**Diagnose.** Long-lived connections (WebSockets, SSE, streaming responses) keep
+the retired release alive until they close or `proxy.drainTimeoutMs` elapses.
+`status` shows the release's `connections.http`/`connections.websocket` and
+`drainStartedAt`.
+
+**Fix.** Draining ends automatically when those connections close, or after
+`proxy.drainTimeoutMs` (then the release is stopped regardless). Lower
+`proxy.drainTimeoutMs` to force-stop sooner, or make clients reconnect (for
+example, have the front end close idle WebSockets on deploy). Once stopped, the
+release is pruned per `releaseRetention`.

package/examples/rollbridge.service

@@ -0,0 +1,48 @@
+# Example systemd unit for the long-running Rollbridge daemon.
+#
+# Install:
+#   sudo cp examples/rollbridge.service /etc/systemd/system/rollbridge.service
+#   # edit User/Group, WorkingDirectory, ExecStart path, and --config below
+#   sudo systemctl daemon-reload
+#   sudo systemctl enable --now rollbridge
+#
+# The daemon is long-lived and survives deploys. Deploys go through
+# `rollbridge deploy` (optionally `--ensure-daemon`), NOT `systemctl restart`.
+# Point --config at a stable, daemon-wide config file (release paths are passed
+# per deploy with `rollbridge deploy --release-path ...`).
+#
+# Find the absolute path to the installed CLI for ExecStart with:
+#   command -v rollbridge
+
+[Unit]
+Description=Rollbridge zero-downtime process supervisor
+After=network.target
+
+[Service]
+Type=simple
+User=deploy
+Group=deploy
+WorkingDirectory=/srv/ticket-server
+ExecStart=/usr/local/bin/rollbridge daemon --config /etc/rollbridge/rollbridge.js
+
+# Optional: variables here are visible to the JS config (process.env) and to
+# `{{env.NAME}}` templates in process commands.
+# EnvironmentFile=/etc/rollbridge/ticket-server.env
+
+Restart=on-failure
+RestartSec=2
+
+# Rollbridge supervises its own child process groups and stops them on SIGTERM,
+# so send SIGTERM to the daemon only and let it drain/stop releases itself;
+# systemd SIGKILLs anything still alive after the timeout.
+KillMode=mixed
+KillSignal=SIGTERM
+
+# Allow time for the daemon to stop its managed processes. Size this above the
+# largest process gracefulStopMs in your config (the daemon SIGKILLs stragglers
+# after that). Note: `systemctl stop` does not drain HTTP/WebSocket connections;
+# draining happens only during `rollbridge deploy` release transitions.
+TimeoutStopSec=120
+
+[Install]
+WantedBy=multi-user.target

package/package.json

@@ -1,7 +1,26 @@
 {
   "name": "rollbridge",
-  "version": "0.1.1",
+  "version": "0.1.4",
   "description": "Zero-downtime process supervisor and local traffic switcher for deploy-managed apps.",
+  "keywords": [
+    "deploy",
+    "zero-downtime",
+    "process-supervisor",
+    "reverse-proxy",
+    "websocket",
+    "rollbridge",
+    "velocious"
+  ],
+  "homepage": "https://github.com/kaspernj/rollbridge#readme",
+  "bugs": {
+    "url": "https://github.com/kaspernj/rollbridge/issues"
+  },
+  "license": "MIT",
+  "author": "kaspernj <kasper@diestoeckels.de>",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/kaspernj/rollbridge.git"
+  },
   "type": "module",
   "bin": {
     "rollbridge": "./bin/rollbridge"

package/src/cli.js

@@ -7,6 +7,7 @@ import {spawn} from "node:child_process"
 import {Command} from "commander"
 import RollbridgeDaemon from "./daemon.js"
 import {loadConfig, parseConfigFile, resolveConfigPath, validateConfig} from "./config.js"
+import {runEnvironmentChecks} from "./doctor.js"
 import {sendControlCommand} from "./control-client.js"
 
 const DEFAULT_DAEMON_START_TIMEOUT_MS = 10000
@@ -153,20 +154,33 @@ export async function runCli(argv) {
     .command("validate")
     .description("Parse the config and report all errors without starting the daemon.")
     .option("-c, --config <path>", "Config file path (defaults to rollbridge.js)")
+    .option("--json", "Output machine-readable JSON")
     .action(async (options) => {
       let configPath
 
       try {
         configPath = await resolveConfigPath(options.config)
       } catch (error) {
-        console.error(error instanceof Error ? error.message : String(error))
+        const message = error instanceof Error ? error.message : String(error)
+
+        if (options.json) console.log(JSON.stringify({config: null, issues: [{fix: "Pass --config or add a rollbridge.js.", message}], path: null, valid: false}, null, 2))
+        else console.error(message)
         process.exitCode = 1
         return
       }
 
       const {config, issues} = await validateConfigFile(configPath)
+      const valid = issues.length === 0
+
+      if (options.json) {
+        const summary = valid ? {application: config.application, processes: config.processes.length, proxy: {host: config.proxy.host, port: config.proxy.port}} : null
+
+        console.log(JSON.stringify({config: summary, issues, path: configPath, valid}, null, 2))
+        if (!valid) process.exitCode = 1
+        return
+      }
 
-      if (issues.length === 0) {
+      if (valid) {
         const processCount = config.processes.length
 
         console.log(`${configPath} is valid: ${processCount} ${processCount === 1 ? "process" : "processes"}, proxy on ${config.proxy.host}:${config.proxy.port}.`)
@@ -183,9 +197,134 @@ export async function runCli(argv) {
       process.exitCode = 1
     })
 
+  program
+    .command("doctor")
+    .description("Check the environment before starting the daemon: config, control socket, and proxy port.")
+    .option("-c, --config <path>", "Config file path (defaults to rollbridge.js)")
+    .option("--json", "Output machine-readable JSON")
+    .action(async (options) => {
+      let configPath
+
+      try {
+        configPath = await resolveConfigPath(options.config)
+      } catch (error) {
+        const message = error instanceof Error ? error.message : String(error)
+
+        if (options.json) console.log(JSON.stringify({checks: [{detail: message, name: "config", ok: false}], ok: false}, null, 2))
+        else console.error(message)
+        process.exitCode = 1
+        return
+      }
+
+      const {config, issues} = await validateConfigFile(configPath)
+      /** @type {import("./doctor.js").DoctorCheck[]} */
+      const checks = []
+
+      if (issues.length > 0) {
+        checks.push({detail: `${issues.length} ${issues.length === 1 ? "issue" : "issues"} — run "rollbridge validate" for details`, name: "config", ok: false})
+      } else {
+        checks.push({detail: `valid: ${config.processes.length} ${config.processes.length === 1 ? "process" : "processes"}, proxy on ${config.proxy.host}:${config.proxy.port}`, name: "config", ok: true})
+        checks.push(...await runEnvironmentChecks(config))
+      }
+
+      const failed = checks.filter((check) => !check.ok).length
+
+      if (options.json) {
+        console.log(JSON.stringify({checks, ok: failed === 0}, null, 2))
+      } else {
+        for (const check of checks) {
+          console.log(`${check.ok ? "✓" : "✗"} ${check.name}: ${check.detail}`)
+        }
+
+        if (failed === 0) console.log("\nAll checks passed.")
+        else console.error(`\n${failed} check${failed === 1 ? "" : "s"} failed.`)
+      }
+
+      if (failed > 0) process.exitCode = 1
+    })
+
+  program
+    .command("logs")
+    .description("Print recent stdout/stderr captured from managed processes.")
+    .option("-c, --config <path>", "Config file path (defaults to rollbridge.js)")
+    .option("--process <id>", "Only show logs for the process with this id")
+    .option("--json", "Output machine-readable JSON")
+    .action(async (options) => {
+      const configPath = await resolveConfigPath(options.config)
+      const config = await loadConfig(configPath)
+      const response = await sendControlCommand({
+        command: {command: "status"},
+        path: config.control.path
+      })
+      const sources = collectLogSources(/** @type {import("./daemon.js").DaemonStatus} */ (response))
+
+      if (options.json) {
+        const filtered = options.process === undefined ? sources : sources.filter((source) => source.id === options.process)
+
+        console.log(JSON.stringify(filtered, null, 2))
+        return
+      }
+
+      console.log(formatLogSources(sources, options.process))
+    })
+
   await program.parseAsync(argv)
 }
 
+/**
+ * @typedef {{id: string, logs: import("./managed-process.js").ManagedProcessLog[], source: string}} LogSource
+ */
+
+/**
+ * Flattens managed-process logs from a daemon status payload, labelling each process by origin.
+ * @param {import("./daemon.js").DaemonStatus} status - Daemon status payload.
+ * @returns {LogSource[]} One entry per managed process.
+ */
+function collectLogSources(status) {
+  /** @type {LogSource[]} */
+  const sources = []
+
+  for (const release of status.releases) {
+    for (const processStatus of release.processes) {
+      sources.push({id: processStatus.id, logs: processStatus.logs, source: `release ${release.releaseId} (${release.state})`})
+    }
+  }
+
+  for (const service of status.services) {
+    sources.push({id: service.process.id, logs: service.process.logs, source: "service"})
+  }
+
+  for (const singleton of status.singletons) {
+    sources.push({id: singleton.process.id, logs: singleton.process.logs, source: "singleton"})
+  }
+
+  return sources
+}
+
+/**
+ * Formats collected log sources for display, optionally filtered to a single process id.
+ * @param {LogSource[]} sources - Collected log sources.
+ * @param {string | undefined} processFilter - Only include the process with this id when set.
+ * @returns {string} Human-readable log output.
+ */
+export function formatLogSources(sources, processFilter) {
+  const matched = processFilter === undefined ? sources : sources.filter((source) => source.id === processFilter)
+
+  if (matched.length === 0) {
+    return processFilter === undefined ? "No managed processes." : `No process found with id "${processFilter}".`
+  }
+
+  return matched
+    .map((source) => {
+      const header = `== ${source.id} [${source.source}] ==`
+
+      if (source.logs.length === 0) return `${header}\n  (no recent output)`
+
+      return `${header}\n${source.logs.map((log) => `  ${log.at} [${log.stream}] ${log.line}`).join("\n")}`
+    })
+    .join("\n\n")
+}
+
 /**
  * Reads, parses, and validates a config file, collecting read, parse, and validation issues.
  * @param {string} configPath - Config file path.

package/src/config.js

@@ -7,12 +7,13 @@ import {pathToFileURL} from "node:url"
 /**
  * @typedef {import("./json.js").JsonValue} JsonValue
  * @typedef {{from: number, to: number}} PortRange
- * @typedef {{path: string, timeoutMs: number, intervalMs: number}} HealthConfig
+ * @typedef {{path: string, startDelayMs: number, timeoutMs: number, intervalMs: number}} HealthConfig
  * @typedef {"proxied" | "companion" | "singleton" | "service"} ProcessPolicy
- * @typedef {{cwd?: string, env: Record<string, string>, gracefulStopMs: number, health?: HealthConfig, id: string, policy: ProcessPolicy, port?: PortRange, restartDelayMs: number, command: string}} ProcessConfig
- * @typedef {{path: string}} ControlConfig
- * @typedef {{drainTimeoutMs: number, forceStopTimeoutMs: number, healthPath: string, healthTimeoutMs: number, host: string, port: number}} ProxyConfig
- * @typedef {{application: string, control: ControlConfig, processes: ProcessConfig[], proxy: ProxyConfig}} RollbridgeConfig
+ * @typedef {{cwd?: string, env: Record<string, string>, gracefulStopMs: number, health?: HealthConfig, id: string, outputLines: number, policy: ProcessPolicy, port?: PortRange, restartDelayMs: number, command: string}} ProcessConfig
+ * @typedef {{mode?: number, path: string}} ControlConfig
+ * @typedef {{drainTimeoutMs: number, forceStopTimeoutMs: number, healthPath: string, healthTimeoutMs: number, host: string, port: number, upstreamHost: string}} ProxyConfig
+ * @typedef {{keep: number, maxAgeMs: number}} ReleaseRetentionConfig
+ * @typedef {{application: string, control: ControlConfig, processes: ProcessConfig[], proxy: ProxyConfig, releaseRetention: ReleaseRetentionConfig}} RollbridgeConfig
  * @typedef {{fix: string, message: string}} ConfigIssue
  */
 
@@ -123,13 +124,15 @@ export function validateConfig(rawConfig, configPath = process.cwd()) {
   const processesSource = arrayAt(source.processes, "processes", issues)
   const proxy = normalizeProxy(proxySource, issues)
   const control = {
+    mode: normalizeSocketMode(controlSource.mode, "control.mode", issues),
     path: normalizeString(controlSource.path, "control.path", issues, {default: `/tmp/rollbridge-${application}.sock`})
   }
   const processes = processesSource.map((processSource, index) => normalizeProcess(processSource, index, proxy, issues))
+  const releaseRetention = normalizeReleaseRetention(objectAt(source.releaseRetention, "releaseRetention", issues, {}), issues)
 
   validateProcessSet(processes, issues)
 
-  return {config: {application, control, processes, proxy}, issues}
+  return {config: {application, control, processes, proxy, releaseRetention}, issues}
 }
 
 /**
@@ -138,16 +141,29 @@ export function validateConfig(rawConfig, configPath = process.cwd()) {
  * @returns {ProxyConfig} Normalized proxy config.
  */
 function normalizeProxy(source, issues) {
+  const host = normalizeString(source.host, "proxy.host", issues, {default: "127.0.0.1"})
+
   return {
     drainTimeoutMs: normalizeNumber(source.drainTimeoutMs, "proxy.drainTimeoutMs", issues, {default: 60000}),
     forceStopTimeoutMs: normalizeNumber(source.forceStopTimeoutMs, "proxy.forceStopTimeoutMs", issues, {default: 10000}),
     healthPath: normalizeString(source.healthPath, "proxy.healthPath", issues, {default: "/ping"}),
     healthTimeoutMs: normalizeNumber(source.healthTimeoutMs, "proxy.healthTimeoutMs", issues, {default: 30000}),
-    host: normalizeString(source.host, "proxy.host", issues, {default: "127.0.0.1"}),
-    port: normalizeNumber(source.port, "proxy.port", issues, {default: 8182})
+    host,
+    port: normalizeNumber(source.port, "proxy.port", issues, {default: 8182}),
+    upstreamHost: normalizeString(source.upstreamHost, "proxy.upstreamHost", issues, {default: defaultUpstreamHost(host)})
   }
 }
 
+/**
+ * @param {string} host - Public proxy bind host.
+ * @returns {string} Default loopback upstream host for wildcard binds.
+ */
+function defaultUpstreamHost(host) {
+  if (host === "0.0.0.0" || host === "::") return "127.0.0.1"
+
+  return host
+}
+
 /**
  * @param {JsonValue} value - Raw process config.
  * @param {number} index - Process index.
@@ -159,7 +175,7 @@ function normalizeProcess(value, index, proxy, issues) {
   if (!isPlainObject(value)) {
     issues.push({fix: `Define processes[${index}] as a mapping with id, policy, and command.`, message: `processes[${index}] must be an object`})
 
-    return {command: "", cwd: undefined, env: {}, gracefulStopMs: proxy.forceStopTimeoutMs, health: undefined, id: "", policy: "companion", port: undefined, restartDelayMs: 1000}
+    return {command: "", cwd: undefined, env: {}, gracefulStopMs: proxy.forceStopTimeoutMs, health: undefined, id: "", outputLines: 50, policy: "companion", port: undefined, restartDelayMs: 1000}
   }
 
   const source = value
@@ -171,12 +187,87 @@ function normalizeProcess(value, index, proxy, issues) {
     gracefulStopMs: normalizeNumber(source.gracefulStopMs, `processes[${index}].gracefulStopMs`, issues, {default: proxy.forceStopTimeoutMs}),
     health: normalizeHealth(source.health, `processes[${index}].health`, proxy, issues),
     id: normalizeString(source.id, `processes[${index}].id`, issues),
+    outputLines: normalizeOutputLines(source.outputLines, `processes[${index}].outputLines`, issues),
     policy: normalizePolicy(source.policy, `processes[${index}].policy`, issues),
     port: normalizePortRange(source.port, `processes[${index}].port`, issues),
     restartDelayMs: normalizeNumber(source.restartDelayMs, `processes[${index}].restartDelayMs`, issues, {default: 1000})
   }
 }
 
+/**
+ * @param {JsonValue} value - Raw output retention value.
+ * @param {string} key - Config key.
+ * @param {ConfigIssue[]} issues - Issue collector.
+ * @returns {number} Recent output lines to retain and report (default 50).
+ */
+function normalizeOutputLines(value, key, issues) {
+  const outputLines = normalizeNumber(value, key, issues, {default: 50})
+
+  if (!Number.isInteger(outputLines) || outputLines < 1) {
+    issues.push({fix: `Set ${key} to a positive integer number of lines, e.g. 50.`, message: `${key} must be a positive integer`})
+
+    return 50
+  }
+
+  return outputLines
+}
+
+/**
+ * @param {Record<string, JsonValue>} source - Raw release retention config.
+ * @param {ConfigIssue[]} issues - Issue collector.
+ * @returns {ReleaseRetentionConfig} Normalized release retention policy.
+ */
+function normalizeReleaseRetention(source, issues) {
+  const keep = normalizeNumber(source.keep, "releaseRetention.keep", issues, {default: 10})
+  const maxAgeMs = normalizeNumber(source.maxAgeMs, "releaseRetention.maxAgeMs", issues, {default: 0})
+
+  return {
+    keep: nonNegativeOrDefault(keep, "releaseRetention.keep", issues, 10, true),
+    maxAgeMs: nonNegativeOrDefault(maxAgeMs, "releaseRetention.maxAgeMs", issues, 0, false)
+  }
+}
+
+/**
+ * @param {number} value - Already type-normalized number.
+ * @param {string} key - Config key.
+ * @param {ConfigIssue[]} issues - Issue collector.
+ * @param {number} fallback - Value to use when invalid.
+ * @param {boolean} requireInteger - Whether the value must be an integer.
+ * @returns {number} The value when non-negative (and integer when required), else the fallback.
+ */
+function nonNegativeOrDefault(value, key, issues, fallback, requireInteger) {
+  if (value < 0 || (requireInteger && !Number.isInteger(value))) {
+    issues.push({fix: `Set ${key} to a non-negative ${requireInteger ? "integer" : "number"}, e.g. ${fallback}.`, message: `${key} must be a non-negative ${requireInteger ? "integer" : "number"}`})
+
+    return fallback
+  }
+
+  return value
+}
+
+/**
+ * @param {JsonValue} value - Raw socket permission mode.
+ * @param {string} key - Config key.
+ * @param {ConfigIssue[]} issues - Issue collector.
+ * @returns {number | undefined} File mode bits (0 to 0o777), or undefined when unset.
+ */
+function normalizeSocketMode(value, key, issues) {
+  if (value === undefined || value === null) return undefined
+
+  if (typeof value === "number") {
+    if (Number.isInteger(value) && value >= 0 && value <= 0o777) return value
+  } else if (typeof value === "string") {
+    const cleaned = value.startsWith("0o") ? value.slice(2) : value
+    const mode = /^[0-7]{1,4}$/.test(cleaned) ? parseInt(cleaned, 8) : Number.NaN
+
+    if (Number.isInteger(mode) && mode >= 0 && mode <= 0o777) return mode
+  }
+
+  issues.push({fix: `Set ${key} to an octal permission string like "660" (or an octal number such as 0o660).`, message: `${key} must be an octal file mode between 0 and 0o777`})
+
+  return undefined
+}
+
 /**
  * Validates cross-process rules: unique ids, exactly one proxied process, and proxied ports.
  * @param {ProcessConfig[]} processes - Normalized processes.
@@ -248,10 +339,29 @@ function normalizeHealth(value, key, proxy, issues) {
   return {
     intervalMs: normalizeNumber(source.intervalMs, `${key}.intervalMs`, issues, {default: 250}),
     path: normalizeString(source.path, `${key}.path`, issues, {default: proxy.healthPath}),
+    startDelayMs: normalizeStartDelayMs(source.startDelayMs, `${key}.startDelayMs`, issues),
     timeoutMs: normalizeNumber(source.timeoutMs, `${key}.timeoutMs`, issues, {default: proxy.healthTimeoutMs})
   }
 }
 
+/**
+ * @param {JsonValue} value - Raw startup delay.
+ * @param {string} key - Config key.
+ * @param {ConfigIssue[]} issues - Issue collector.
+ * @returns {number} Milliseconds to wait before the first health probe (default 0).
+ */
+function normalizeStartDelayMs(value, key, issues) {
+  const startDelayMs = normalizeNumber(value, key, issues, {default: 0})
+
+  if (startDelayMs < 0) {
+    issues.push({fix: `Set ${key} to a non-negative number of milliseconds, e.g. 0 or 2000.`, message: `${key} must be a non-negative number`})
+
+    return 0
+  }
+
+  return startDelayMs
+}
+
 /**
  * @param {JsonValue} value - Raw env config.
  * @param {string} key - Config key.