rollbridge 0.1.6 → 0.1.7

package/README.md

@@ -174,6 +174,20 @@ stop them before restarting the daemon. A clean `shutdown` removes the file. See
 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:
 
@@ -466,6 +480,13 @@ 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

package/TODO.md

@@ -25,7 +25,7 @@ This roadmap tracks planned Rollbridge features and documentation. Rollbridge sh
   - [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.
-- [ ] Worker auto-restart and restart policy controls.
+- [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).
   - [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.
@@ -50,7 +50,7 @@ This roadmap tracks planned Rollbridge features and documentation. Rollbridge sh
   - [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.
-- [ ] Observability and diagnostics.
+- [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`).
   - [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.)
@@ -58,7 +58,7 @@ This roadmap tracks planned Rollbridge features and documentation. Rollbridge sh
   - [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.
   - [x] Extend `doctor` with state-path checks: state-path directory writability and orphaned-process reporting from a prior state file.

package/docs/cli.md

@@ -164,6 +164,26 @@ 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`
 
 ```

package/docs/config.md

@@ -23,6 +23,7 @@ export default {
 | --- | --- | --- | --- |
 | `application` | string | basename of the config file's directory | Names the app; used in the default control-socket path and the `ROLLBRIDGE_APPLICATION` env var. |
 | `control` | object | — | Control-socket settings (see below). |
+| `legacyTakeover` | object | unset | Optional matchers for `rollbridge predeploy-cleanup` to stop pre-Rollbridge supervisors during first handover (see below). |
 | `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). |
@@ -88,6 +89,38 @@ statePath: "/var/lib/rollbridge/ticket-server.state.json"
 
 Leave `statePath` unset to disable persistence (the default).
 
+## `legacyTakeover`
+
+`legacyTakeover` lets deploy scripts run `rollbridge predeploy-cleanup` during
+the first migration from an old supervisor. The command only uses these matchers
+when no active Rollbridge release is running. If a Rollbridge daemon already has
+an active release, it exits without stopping legacy processes.
+
+| Field | Type | Default | Description |
+| --- | --- | --- | --- |
+| `legacyTakeover.screens` | array of strings | `[]` | GNU Screen session names to stop with `screen -S <name> -X quit`. |
+| `legacyTakeover.processes` | array | `[]` | Process command-line matchers. Each entry must define `includes`, and may define `name`. |
+| `legacyTakeover.forceStopTimeoutMs` | number | `proxy.forceStopTimeoutMs` | Grace period after `SIGTERM` before `SIGKILL` is sent to matched legacy processes. |
+
+Each `legacyTakeover.processes[]` entry:
+
+| Field | Type | Default | Description |
+| --- | --- | --- | --- |
+| `includes` | array of strings | **required** | Every string must appear in a process command line for it to be considered a legacy seed process. Descendants of seed processes are stopped too. |
+| `name` | string | generated | Human-readable label for diagnostics. |
+
+Example:
+
+```js
+legacyTakeover: {
+  forceStopTimeoutMs: 10000,
+  screens: ["ticket-server"],
+  processes: [
+    {name: "legacy web", includes: ["/home/dev/ticket-server/", "velocious server", "--port 8082"]}
+  ]
+}
+```
+
 ## `processes[]`
 
 | Field | Type | Default | Description |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rollbridge",
-  "version": "0.1.6",
+  "version": "0.1.7",
   "description": "Zero-downtime process supervisor and local traffic switcher for deploy-managed apps.",
   "keywords": [
     "deploy",

package/src/cli.js

@@ -8,6 +8,7 @@ import {Command} from "commander"
 import RollbridgeDaemon from "./daemon.js"
 import {loadConfig, parseConfigFile, resolveConfigPath, validateConfig} from "./config.js"
 import {runEnvironmentChecks, runReleaseChecks} from "./doctor.js"
+import {predeployCleanup} from "./predeploy-cleanup.js"
 import {recoverOrphans} from "./recover.js"
 import {sendControlCommand} from "./control-client.js"
 
@@ -357,6 +358,19 @@ export async function runCli(argv) {
       console.log(formatEvents(events))
     })
 
+  program
+    .command("predeploy-cleanup")
+    .description("Prepare a host for deploy: recover Rollbridge orphans and stop configured legacy processes when no release is active.")
+    .option("-c, --config <path>", "Config file path (defaults to rollbridge.js)")
+    .option("--release-path <path>", "Pending release path; restarts the daemon if this release changes Rollbridge itself")
+    .action(async (options) => {
+      const configPath = await resolveConfigPath(options.config)
+      const config = await loadConfig(configPath)
+      const result = await predeployCleanup({config, releasePath: options.releasePath})
+
+      console.log(formatPredeployCleanupResult(result))
+    })
+
   program
     .command("recover")
     .description("Stop orphaned processes left by a crashed daemon (reads statePath; lists them unless --force).")
@@ -399,6 +413,29 @@ export async function runCli(argv) {
   await program.parseAsync(argv)
 }
 
+/**
+ * @param {import("./predeploy-cleanup.js").PredeployCleanupResult} result - Cleanup result.
+ * @returns {string} Human-readable summary.
+ */
+function formatPredeployCleanupResult(result) {
+  if (result.action === "daemon-active") {
+    return "Rollbridge daemon already has an active release; no legacy cleanup needed."
+  }
+
+  const lines = []
+
+  if (result.action === "daemon-stopped") {
+    lines.push("Stopped existing Rollbridge daemon before deploy.")
+  } else {
+    lines.push("No active Rollbridge daemon found.")
+  }
+
+  lines.push(`Recovered ${result.recoveredOrphans} Rollbridge orphaned process${result.recoveredOrphans === 1 ? "" : "es"}.`)
+  lines.push(`Stopped ${result.legacyProcesses.length} legacy process${result.legacyProcesses.length === 1 ? "" : "es"}.`)
+
+  return lines.join("\n")
+}
+
 /**
  * @typedef {import("./recover.js").OrphanProcess} OrphanProcess
  */

package/src/config.js

@@ -16,8 +16,10 @@ import {pathToFileURL} from "node:url"
  * @typedef {{cwd?: string, env: Record<string, string>, gracefulStopMs: number, health?: HealthConfig, id: string, lifecycle: LifecycleConfig, memory?: MemoryConfig, nonBlockingDrain: boolean, outputLines: number, policy: ProcessPolicy, port?: PortRange, replicas: number, restart: RestartConfig, restartDelayMs: number, stopSignal: string, command: string}} ProcessConfig
  * @typedef {{group?: number | string, mode?: number, owner?: number | string, path: string}} ControlConfig
  * @typedef {{drainTimeoutMs: number, forceStopTimeoutMs: number, healthPath: string, healthTimeoutMs: number, host: string, port: number, upstreamHost: string}} ProxyConfig
+ * @typedef {{includes: string[], name: string}} LegacyTakeoverProcessConfig
+ * @typedef {{forceStopTimeoutMs: number, processes: LegacyTakeoverProcessConfig[], screens: string[]}} LegacyTakeoverConfig
  * @typedef {{keep: number, maxAgeMs: number}} ReleaseRetentionConfig
- * @typedef {{application: string, control: ControlConfig, processes: ProcessConfig[], proxy: ProxyConfig, releaseRetention: ReleaseRetentionConfig, statePath?: string}} RollbridgeConfig
+ * @typedef {{application: string, control: ControlConfig, legacyTakeover?: LegacyTakeoverConfig, processes: ProcessConfig[], proxy: ProxyConfig, releaseRetention: ReleaseRetentionConfig, statePath?: string}} RollbridgeConfig
  * @typedef {{fix: string, message: string}} ConfigIssue
  */
 
@@ -134,12 +136,13 @@ export function validateConfig(rawConfig, configPath = process.cwd()) {
     path: normalizeString(controlSource.path, "control.path", issues, {default: `/tmp/rollbridge-${application}.sock`})
   }
   const processes = processesSource.map((processSource, index) => normalizeProcess(processSource, index, proxy, issues))
+  const legacyTakeover = normalizeLegacyTakeover(source.legacyTakeover, proxy, issues)
   const releaseRetention = normalizeReleaseRetention(objectAt(source.releaseRetention, "releaseRetention", issues, {}), issues)
   const statePath = source.statePath === undefined || source.statePath === null ? undefined : normalizeString(source.statePath, "statePath", issues)
 
   validateProcessSet(processes, issues)
 
-  return {config: {application, control, processes, proxy, releaseRetention, statePath}, issues}
+  return {config: {application, control, legacyTakeover, processes, proxy, releaseRetention, statePath}, issues}
 }
 
 /**
@@ -340,6 +343,102 @@ function normalizeLifecycle(value, key, issues) {
   return lifecycle
 }
 
+/**
+ * @param {JsonValue} value - Raw legacy takeover config.
+ * @param {ProxyConfig} proxy - Proxy config defaults.
+ * @param {ConfigIssue[]} issues - Issue collector.
+ * @returns {LegacyTakeoverConfig | undefined} Normalized legacy takeover config, or undefined when omitted.
+ */
+function normalizeLegacyTakeover(value, proxy, issues) {
+  if (value === undefined || value === null) return undefined
+
+  if (!isPlainObject(value)) {
+    issues.push({fix: "Set legacyTakeover to a mapping with screens and/or processes.", message: "legacyTakeover must be an object"})
+
+    return {forceStopTimeoutMs: proxy.forceStopTimeoutMs, processes: [], screens: []}
+  }
+
+  const forceStopTimeoutMs = normalizeNumber(value.forceStopTimeoutMs, "legacyTakeover.forceStopTimeoutMs", issues, {default: proxy.forceStopTimeoutMs})
+  const screens = normalizeStringList(value.screens, "legacyTakeover.screens", issues)
+  const processes = normalizeLegacyTakeoverProcesses(value.processes, issues)
+
+  if (screens.length === 0 && processes.length === 0) {
+    issues.push({fix: "Set legacyTakeover.screens or legacyTakeover.processes so predeploy-cleanup knows what legacy processes it may stop.", message: "legacyTakeover must define at least one screen or process matcher"})
+  }
+
+  return {
+    forceStopTimeoutMs: nonNegativeOrDefault(forceStopTimeoutMs, "legacyTakeover.forceStopTimeoutMs", issues, proxy.forceStopTimeoutMs, false),
+    processes,
+    screens
+  }
+}
+
+/**
+ * @param {JsonValue} value - Raw list value.
+ * @param {string} key - Config key.
+ * @param {ConfigIssue[]} issues - Issue collector.
+ * @returns {string[]} Normalized strings.
+ */
+function normalizeStringList(value, key, issues) {
+  if (value === undefined || value === null) return []
+
+  if (!Array.isArray(value)) {
+    issues.push({fix: `Set ${key} to a list of strings.`, message: `${key} must be an array`})
+
+    return []
+  }
+
+  return value.flatMap((entry, index) => {
+    if (typeof entry === "string" && entry.length > 0) return [entry]
+
+    issues.push({fix: `Set ${key}[${index}] to a non-empty string.`, message: `${key}[${index}] must be a non-empty string`})
+    return []
+  })
+}
+
+/**
+ * @param {JsonValue} value - Raw legacy process matchers.
+ * @param {ConfigIssue[]} issues - Issue collector.
+ * @returns {LegacyTakeoverProcessConfig[]} Normalized process matchers.
+ */
+function normalizeLegacyTakeoverProcesses(value, issues) {
+  if (value === undefined || value === null) return []
+
+  if (!Array.isArray(value)) {
+    issues.push({fix: "Set legacyTakeover.processes to a list of mappings with includes strings.", message: "legacyTakeover.processes must be an array"})
+
+    return []
+  }
+
+  return value.flatMap((entry, index) => normalizeLegacyTakeoverProcess(entry, index, issues))
+}
+
+/**
+ * @param {JsonValue} value - Raw legacy process matcher.
+ * @param {number} index - Matcher index.
+ * @param {ConfigIssue[]} issues - Issue collector.
+ * @returns {LegacyTakeoverProcessConfig[]} Normalized matcher, or an empty list when invalid.
+ */
+function normalizeLegacyTakeoverProcess(value, index, issues) {
+  const key = `legacyTakeover.processes[${index}]`
+
+  if (!isPlainObject(value)) {
+    issues.push({fix: `Set ${key} to a mapping with includes strings.`, message: `${key} must be an object`})
+
+    return []
+  }
+
+  const includes = normalizeStringList(value.includes, `${key}.includes`, issues)
+  if (includes.length === 0) {
+    issues.push({fix: `Set ${key}.includes to one or more command-line substrings that identify the legacy process.`, message: `${key}.includes must contain at least one matcher`})
+  }
+
+  return [{
+    includes,
+    name: normalizeString(value.name, `${key}.name`, issues, {default: `legacy process ${index + 1}`})
+  }]
+}
+
 /**
  * @param {JsonValue} value - Raw stop signal.
  * @param {string} key - Config key.

package/src/predeploy-cleanup.js

@@ -0,0 +1,340 @@
+// @ts-check
+
+import fs from "node:fs"
+import path from "node:path"
+import {spawnSync} from "node:child_process"
+import {setTimeout as sleep} from "node:timers/promises"
+import {inspectControlSocket} from "./daemon.js"
+import {recoverOrphans} from "./recover.js"
+import {sendControlCommand} from "./control-client.js"
+
+/**
+ * @typedef {import("./json.js").JsonValue} JsonValue
+ * @typedef {{pid: number, parentPid: number, args: string}} ProcessRow
+ * @typedef {{action: string, legacyProcesses: ProcessRow[], recoveredOrphans: number}} PredeployCleanupResult
+ */
+
+/**
+ * Prepares a host for a Rollbridge deploy by handling the two cases that can block a fresh
+ * daemon startup: orphaned Rollbridge-managed pids from a crashed daemon, and explicitly
+ * configured legacy processes from the pre-Rollbridge supervisor.
+ * @param {object} args - Options.
+ * @param {import("./config.js").RollbridgeConfig} args.config - Rollbridge config.
+ * @param {(socketPath: string) => Promise<import("./daemon.js").ControlSocketInspection>} [args.inspectSocket] - Control socket probe.
+ * @param {string} [args.releasePath] - Pending release path, used to restart the daemon when this release changes Rollbridge itself.
+ * @param {(args: {command: Record<string, JsonValue>, path: string}) => Promise<Record<string, JsonValue>>} [args.sendCommand] - Control command sender.
+ * @param {(command: string, args: string[]) => import("node:child_process").SpawnSyncReturns<Buffer>} [args.runCommand] - Command runner.
+ * @param {(pid: number, signal: string) => void} [args.killProcess] - Signal sender.
+ * @param {(args: {config: import("./config.js").RollbridgeConfig, force: boolean}) => Promise<import("./recover.js").RecoverResult>} [args.recover] - Orphan recovery function.
+ * @returns {Promise<PredeployCleanupResult>} Cleanup result.
+ */
+export async function predeployCleanup({
+  config,
+  inspectSocket = inspectControlSocket,
+  killProcess = process.kill,
+  releasePath,
+  recover = recoverOrphans,
+  runCommand = spawnSync,
+  sendCommand = sendControlCommand
+}) {
+  const inspection = await inspectSocket(config.control.path)
+
+  if (inspection.alive) {
+    const status = await activeDaemonStatus({config, inspection, sendCommand})
+
+    if (status.activeReleaseId && daemonMatchesPendingRelease({config, releasePath, status})) {
+      return {action: "daemon-active", legacyProcesses: [], recoveredOrphans: 0}
+    }
+
+    await sendCommand({command: {command: "shutdown"}, path: config.control.path})
+    await waitForControlSocketShutdown({config, inspectSocket})
+  }
+
+  const recoveredOrphans = await recoverConfiguredOrphans(config, recover)
+  const legacyProcesses = await stopLegacyProcesses({config, killProcess, runCommand})
+
+  return {
+    action: inspection.alive ? "daemon-stopped" : "no-daemon-cleaned",
+    legacyProcesses,
+    recoveredOrphans
+  }
+}
+
+/**
+ * @param {object} args - Options.
+ * @param {import("./config.js").RollbridgeConfig} args.config - Rollbridge config.
+ * @param {import("./daemon.js").ControlSocketInspection} args.inspection - Socket inspection.
+ * @param {(args: {command: Record<string, JsonValue>, path: string}) => Promise<Record<string, JsonValue>>} args.sendCommand - Control command sender.
+ * @returns {Promise<import("./daemon.js").DaemonStatus>} Daemon status.
+ */
+async function activeDaemonStatus({config, inspection, sendCommand}) {
+  if (inspection.application === undefined) {
+    throw new Error(`A non-Rollbridge process is using ${config.control.path}; refusing predeploy cleanup.`)
+  }
+
+  if (inspection.application !== config.application) {
+    throw new Error(`A Rollbridge daemon for "${inspection.application}" is using ${config.control.path}; expected "${config.application}".`)
+  }
+
+  const status = await sendCommand({command: {command: "status"}, path: config.control.path})
+
+  return /** @type {import("./daemon.js").DaemonStatus} */ (status)
+}
+
+/**
+ * @param {object} args - Options.
+ * @param {import("./config.js").RollbridgeConfig} args.config - Rollbridge config.
+ * @param {string} [args.releasePath] - Pending release path.
+ * @param {import("./daemon.js").DaemonStatus} args.status - Active daemon status.
+ * @returns {boolean} True when the active daemon can be reused for this deploy.
+ */
+function daemonMatchesPendingRelease({config, releasePath, status}) {
+  if (!proxyMatchesConfig(status.proxy, config.proxy)) return false
+  if (releasePath !== undefined && rollbridgePackageChanged({releasePath, status})) return false
+
+  return true
+}
+
+/**
+ * @param {import("./daemon.js").DaemonStatus["proxy"]} currentProxy - Current proxy status.
+ * @param {import("./config.js").ProxyConfig} expectedProxy - Pending release proxy config.
+ * @returns {boolean} True when the current daemon proxy matches the pending config.
+ */
+function proxyMatchesConfig(currentProxy, expectedProxy) {
+  return currentProxy.host === expectedProxy.host &&
+    currentProxy.port === expectedProxy.port &&
+    currentProxy.upstreamHost === expectedProxy.upstreamHost
+}
+
+/**
+ * @param {object} args - Options.
+ * @param {string} args.releasePath - Pending release path.
+ * @param {import("./daemon.js").DaemonStatus} args.status - Active daemon status.
+ * @returns {boolean} True when the pending release uses a different Rollbridge package version.
+ */
+function rollbridgePackageChanged({releasePath, status}) {
+  const activeRelease = status.releases.find((release) => release.releaseId === status.activeReleaseId)
+  if (activeRelease === undefined) return false
+
+  const releaseVersion = rollbridgePackageVersion(releasePath)
+  const activeVersion = rollbridgePackageVersion(activeRelease.releasePath)
+
+  return releaseVersion !== undefined &&
+    activeVersion !== undefined &&
+    releaseVersion !== activeVersion
+}
+
+/**
+ * @param {string} releasePath - Release path containing node_modules.
+ * @returns {string | undefined} Installed Rollbridge package version.
+ */
+function rollbridgePackageVersion(releasePath) {
+  try {
+    const packageJson = JSON.parse(fs.readFileSync(path.join(releasePath, "node_modules", "rollbridge", "package.json"), "utf8"))
+
+    if (packageJson && typeof packageJson === "object" && "version" in packageJson && typeof packageJson.version === "string") {
+      return packageJson.version
+    }
+  } catch (error) {
+    if (error && typeof error === "object" && "code" in error && error.code === "ENOENT") return undefined
+
+    throw error
+  }
+
+  return undefined
+}
+
+/**
+ * @param {object} args - Options.
+ * @param {import("./config.js").RollbridgeConfig} args.config - Rollbridge config.
+ * @param {(socketPath: string) => Promise<import("./daemon.js").ControlSocketInspection>} args.inspectSocket - Control socket probe.
+ * @returns {Promise<void>} Resolves after the socket stops accepting Rollbridge commands.
+ */
+async function waitForControlSocketShutdown({config, inspectSocket}) {
+  const deadline = Date.now() + 30000
+
+  while (true) {
+    const inspection = await inspectSocket(config.control.path)
+    if (!inspection.alive) return
+
+    if (Date.now() >= deadline) {
+      throw new Error(`Timed out waiting for Rollbridge daemon at ${config.control.path} to shut down.`)
+    }
+
+    await sleep(250)
+  }
+}
+
+/**
+ * @param {import("./config.js").RollbridgeConfig} config - Rollbridge config.
+ * @param {(args: {config: import("./config.js").RollbridgeConfig, force: boolean}) => Promise<import("./recover.js").RecoverResult>} recover - Orphan recovery function.
+ * @returns {Promise<number>} Number of orphans found.
+ */
+async function recoverConfiguredOrphans(config, recover) {
+  if (config.statePath === undefined) return 0
+
+  const result = await recover({config, force: true})
+
+  if ("error" in result) {
+    throw new Error(result.error)
+  }
+
+  if (result.remaining.length > 0) {
+    throw new Error(`Could not stop ${result.remaining.length} Rollbridge orphaned process${result.remaining.length === 1 ? "" : "es"}.`)
+  }
+
+  return result.orphans.length
+}
+
+/**
+ * @param {object} args - Options.
+ * @param {import("./config.js").RollbridgeConfig} args.config - Rollbridge config.
+ * @param {(command: string, args: string[]) => import("node:child_process").SpawnSyncReturns<Buffer>} args.runCommand - Command runner.
+ * @param {(pid: number, signal: string) => void} args.killProcess - Signal sender.
+ * @returns {Promise<ProcessRow[]>} Stopped legacy processes.
+ */
+async function stopLegacyProcesses({config, killProcess, runCommand}) {
+  const takeoverConfig = config.legacyTakeover
+  if (takeoverConfig === undefined) return []
+
+  for (const screenName of takeoverConfig.screens) {
+    runCommand("screen", ["-S", screenName, "-X", "quit"])
+  }
+
+  const stoppedProcesses = await stopProcessTree({
+    killProcess,
+    processRows: legacyProcesses(config),
+    timeoutMs: takeoverConfig.forceStopTimeoutMs
+  })
+  const remainingProcesses = legacyProcesses(config)
+
+  if (remainingProcesses.length > 0) {
+    const details = remainingProcesses.map((row) => `${row.pid} ${row.args}`).join("\n")
+
+    throw new Error(`Refusing Rollbridge deploy while legacy processes are still running:\n${details}`)
+  }
+
+  return stoppedProcesses
+}
+
+/**
+ * @param {import("./config.js").RollbridgeConfig} config - Rollbridge config.
+ * @returns {ProcessRow[]} Legacy process rows and their descendants.
+ */
+function legacyProcesses(config) {
+  const rows = processRows()
+  const protectedPids = protectedProcessIds(rows)
+  const legacyPids = new Set(rows.filter((row) => legacySeedProcess(row, config, protectedPids)).map((row) => row.pid))
+  let changed = true
+
+  while (changed) {
+    changed = false
+
+    for (const row of rows) {
+      if (!legacyPids.has(row.pid) && legacyPids.has(row.parentPid)) {
+        legacyPids.add(row.pid)
+        changed = true
+      }
+    }
+  }
+
+  return rows.filter((row) => legacyPids.has(row.pid))
+}
+
+/**
+ * @param {ProcessRow} row - Process row.
+ * @param {import("./config.js").RollbridgeConfig} config - Rollbridge config.
+ * @param {Set<number>} protectedPids - Current cleanup process and ancestors.
+ * @returns {boolean} True when the row identifies a configured legacy process.
+ */
+function legacySeedProcess(row, config, protectedPids) {
+  const takeoverConfig = config.legacyTakeover
+  if (takeoverConfig === undefined || protectedPids.has(row.pid)) return false
+
+  if (takeoverConfig.screens.some((screenName) => row.args.includes(`SCREEN -dmS ${screenName}`))) {
+    return true
+  }
+
+  return takeoverConfig.processes.some((processConfig) => (
+    processConfig.includes.every((matcher) => row.args.includes(matcher))
+  ))
+}
+
+/**
+ * @param {ProcessRow[]} rows - Current process table rows.
+ * @returns {Set<number>} Pids that belong to the running cleanup command.
+ */
+function protectedProcessIds(rows) {
+  const byPid = new Map(rows.map((row) => [row.pid, row]))
+  const protectedPids = new Set([process.pid])
+  let parentPid = process.ppid
+
+  while (parentPid > 0 && !protectedPids.has(parentPid)) {
+    protectedPids.add(parentPid)
+    parentPid = byPid.get(parentPid)?.parentPid || 0
+  }
+
+  return protectedPids
+}
+
+/** @returns {ProcessRow[]} Current process table rows. */
+function processRows() {
+  const result = spawnSync("ps", ["-eo", "pid=,ppid=,args="], {encoding: "utf8"})
+
+  if (result.error) throw result.error
+  if (result.status !== 0) throw new Error(`Failed to inspect running processes: ${result.stderr}`)
+
+  return result.stdout.split("\n").flatMap((line) => {
+    const match = line.match(/^\s*(\d+)\s+(\d+)\s+(.+)$/)
+    if (!match) return []
+
+    const pid = Number(match[1])
+    const parentPid = Number(match[2])
+
+    return [{args: match[3], parentPid, pid}]
+  })
+}
+
+/**
+ * @param {object} args - Options.
+ * @param {(pid: number, signal: string) => void} args.killProcess - Signal sender.
+ * @param {ProcessRow[]} args.processRows - Processes to stop.
+ * @param {number} args.timeoutMs - Grace period before SIGKILL.
+ * @returns {Promise<ProcessRow[]>} Processes that were signaled.
+ */
+async function stopProcessTree({killProcess, processRows, timeoutMs}) {
+  /** @type {ProcessRow[]} */
+  const stoppedProcesses = []
+
+  for (const row of processRows) {
+    if (sendSignal(row.pid, "SIGTERM", killProcess)) stoppedProcesses.push(row)
+  }
+
+  if (stoppedProcesses.length === 0) return []
+
+  await sleep(timeoutMs)
+
+  for (const row of processRows) {
+    sendSignal(row.pid, "SIGKILL", killProcess)
+  }
+
+  return stoppedProcesses
+}
+
+/**
+ * @param {number} pid - Process id.
+ * @param {string} signal - Signal name.
+ * @param {(pid: number, signal: string) => void} killProcess - Signal sender.
+ * @returns {boolean} True when the signal was sent, false when the process was already gone.
+ */
+function sendSignal(pid, signal, killProcess) {
+  try {
+    killProcess(pid, signal)
+
+    return true
+  } catch (error) {
+    if (error && typeof error === "object" && "code" in error && error.code === "ESRCH") return false
+
+    throw error
+  }
+}

package/test/completion.test.js

@@ -41,7 +41,7 @@ test("completion bash prints a sourceable script with commands and option flags"
 
   assert.notEqual(code, 1)
   assert.match(output, /complete -F _rollbridge rollbridge/)
-  assert.match(output, /compgen -W "daemon deploy rollback ensure-daemon status stop restart shutdown validate doctor logs events recover completion"/)
+  assert.match(output, /compgen -W "daemon deploy rollback ensure-daemon status stop restart shutdown validate doctor logs events predeploy-cleanup recover completion"/)
   // A command's own options are completed after the command.
   assert.match(output, /deploy\)\n\s+opts="[^"]*--release-path[^"]*"/)
   assert.match(output, /restart\)\n\s+opts="[^"]*--policy[^"]*"/)
@@ -52,7 +52,7 @@ test("completion zsh prints a #compdef script with per-command options", async (
 
   assert.match(output, /^#compdef rollbridge/)
   assert.match(output, /compdef _rollbridge rollbridge/)
-  assert.match(output, /commands=\(daemon deploy rollback ensure-daemon status stop restart shutdown validate doctor logs events recover completion\)/)
+  assert.match(output, /commands=\(daemon deploy rollback ensure-daemon status stop restart shutdown validate doctor logs events predeploy-cleanup recover completion\)/)
   assert.match(output, /events\) compadd -- [^\n]*--limit/)
 })
 

package/test/config-validation.test.js

@@ -70,6 +70,47 @@ test("validateConfig defaults wildcard proxy upstreams to loopback", () => {
   assert.equal(config.proxy.upstreamHost, "127.0.0.1")
 })
 
+test("validateConfig accepts legacy takeover screens and process matchers", () => {
+  const {config, issues} = validateConfig({
+    application: "demo",
+    control: {path: "/tmp/demo.sock"},
+    legacyTakeover: {
+      forceStopTimeoutMs: 250,
+      processes: [
+        {includes: ["/srv/demo/", "velocious server", "--port 4500"], name: "legacy web"}
+      ],
+      screens: ["demo-backend"]
+    },
+    processes: [
+      {command: "run web", id: "web", policy: "proxied", port: {from: 18000, to: 18099}}
+    ],
+    proxy: {host: "127.0.0.1", port: 8182}
+  })
+
+  assert.deepEqual(issues, [])
+  assert.deepEqual(config.legacyTakeover, {
+    forceStopTimeoutMs: 250,
+    processes: [
+      {includes: ["/srv/demo/", "velocious server", "--port 4500"], name: "legacy web"}
+    ],
+    screens: ["demo-backend"]
+  })
+})
+
+test("validateConfig rejects empty legacy takeover config", () => {
+  const {issues} = validateConfig({
+    application: "demo",
+    control: {path: "/tmp/demo.sock"},
+    legacyTakeover: {},
+    processes: [
+      {command: "run web", id: "web", policy: "proxied", port: {from: 18000, to: 18099}}
+    ],
+    proxy: {host: "127.0.0.1", port: 8182}
+  })
+
+  assert.ok(issues.some((issue) => issue.message === "legacyTakeover must define at least one screen or process matcher"), JSON.stringify(issues))
+})
+
 test("validateConfig defaults outputLines and accepts a positive override", () => {
   const {config, issues} = validateConfig({
     application: "demo",

package/test/predeploy-cleanup.test.js

@@ -0,0 +1,131 @@
+// @ts-check
+
+import assert from "node:assert/strict"
+import {spawn} from "node:child_process"
+import {once} from "node:events"
+import fs from "node:fs/promises"
+import os from "node:os"
+import path from "node:path"
+import test from "node:test"
+import {normalizeConfig} from "../src/config.js"
+import {isProcessAlive} from "../src/state-store.js"
+import {predeployCleanup} from "../src/predeploy-cleanup.js"
+
+/**
+ * @param {string} dir - Working directory.
+ * @param {string} marker - Unique process marker.
+ * @returns {import("../src/config.js").RollbridgeConfig} Test config.
+ */
+function buildConfig(dir, marker) {
+  return normalizeConfig({
+    application: "predeploy-cleanup-test",
+    control: {path: path.join(dir, "rollbridge.sock")},
+    legacyTakeover: {
+      forceStopTimeoutMs: 50,
+      processes: [{includes: [marker], name: "legacy marker process"}]
+    },
+    processes: [{command: "true", id: "web", policy: "proxied", port: {from: 0, to: 0}}],
+    proxy: {host: "127.0.0.1", port: 0}
+  })
+}
+
+test("predeploy cleanup stops configured legacy process when no daemon is active", async () => {
+  const dir = await fs.mkdtemp(path.join(os.tmpdir(), "rollbridge-predeploy-cleanup-"))
+  const marker = `rollbridge-app-legacy-marker-${process.pid}-${Date.now()}`
+  const legacy = spawn(process.execPath, ["-e", "setInterval(() => {}, 1000)", marker], {stdio: "ignore"})
+
+  await once(legacy, "spawn")
+
+  try {
+    const result = await predeployCleanup({config: buildConfig(dir, marker)})
+
+    assert.equal(result.action, "no-daemon-cleaned")
+    assert.equal(result.recoveredOrphans, 0)
+    assert.equal(result.legacyProcesses.length, 1)
+    assert.equal(result.legacyProcesses[0].pid, legacy.pid)
+    assert.ok(legacy.pid === undefined || !isProcessAlive(legacy.pid))
+  } finally {
+    legacy.kill("SIGKILL")
+    await fs.rm(dir, {force: true, recursive: true})
+  }
+})
+
+test("predeploy cleanup leaves legacy processes alone when daemon already has an active release", async () => {
+  const dir = await fs.mkdtemp(path.join(os.tmpdir(), "rollbridge-predeploy-cleanup-"))
+
+  try {
+    const result = await predeployCleanup({
+      config: buildConfig(dir, "unused-marker"),
+      inspectSocket: async () => ({
+        activeReleaseId: "v1",
+        alive: true,
+        application: "predeploy-cleanup-test"
+      }),
+      sendCommand: async () => ({
+        activeReleaseId: "v1",
+        application: "predeploy-cleanup-test",
+        control: {path: path.join(dir, "rollbridge.sock")},
+        orphans: [],
+        proxy: {host: "127.0.0.1", port: 0, upstreamHost: "127.0.0.1"},
+        releases: [],
+        services: [],
+        singletons: [],
+        status: "success"
+      })
+    })
+
+    assert.deepEqual(result, {
+      action: "daemon-active",
+      legacyProcesses: [],
+      recoveredOrphans: 0
+    })
+  } finally {
+    await fs.rm(dir, {force: true, recursive: true})
+  }
+})
+
+test("predeploy cleanup stops an active daemon when the proxy config changed", async () => {
+  const dir = await fs.mkdtemp(path.join(os.tmpdir(), "rollbridge-predeploy-cleanup-"))
+  /** @type {Record<string, import("../src/json.js").JsonValue>[]} */
+  const commands = []
+  let inspectCount = 0
+
+  try {
+    const result = await predeployCleanup({
+      config: buildConfig(dir, "unused-marker"),
+      inspectSocket: async () => {
+        inspectCount += 1
+
+        return {
+          activeReleaseId: inspectCount === 1 ? "v1" : undefined,
+          alive: inspectCount === 1,
+          application: inspectCount === 1 ? "predeploy-cleanup-test" : undefined
+        }
+      },
+      sendCommand: async ({command}) => {
+        commands.push(command)
+
+        if (command.command === "status") {
+          return {
+            activeReleaseId: "v1",
+            application: "predeploy-cleanup-test",
+            control: {path: path.join(dir, "rollbridge.sock")},
+            orphans: [],
+            proxy: {host: "127.0.0.1", port: 9999, upstreamHost: "127.0.0.1"},
+            releases: [],
+            services: [],
+            singletons: [],
+            status: "success"
+          }
+        }
+
+        return {status: "success"}
+      }
+    })
+
+    assert.equal(result.action, "daemon-stopped")
+    assert.deepEqual(commands.map((command) => command.command), ["status", "shutdown"])
+  } finally {
+    await fs.rm(dir, {force: true, recursive: true})
+  }
+})