rollbridge 0.1.12 → 0.1.14

package/README.md

@@ -399,6 +399,23 @@ Start the daemon:
 rollbridge daemon --config rollbridge.js
 ```
 
+Start the daemon and bootstrap an exact prepared release before leaving it in
+the foreground (for example from a boot-time service manager):
+
+```bash
+rollbridge daemon --config /srv/ticket-server/rollbridge.js \
+  --release-path /srv/ticket-server/releases/20260813090000/ticket-server \
+  --release-id 20260813090000 --revision abc123
+```
+
+The four bootstrap inputs are all-or-nothing and use absolute config/release
+paths. Rollbridge binds its proxy, activates the release through the normal
+deploy path, then exposes the control socket and stays foreground. A failed
+activation stops only processes started by that attempt and exits non-zero;
+persisted processes from a previous daemon are reported as orphans and are never
+recovered or killed implicitly; their live PID records remain in `statePath` for
+explicit recovery.
+
 Start the daemon only when it is not already running:
 
 ```bash

package/docs/cli.md

@@ -24,6 +24,7 @@ process-policy details.
 
 ```
 rollbridge daemon [--config <path>]
+                  [--release-path <path> --release-id <id> --revision <sha>]
 ```
 
 Runs the supervisor in the foreground: binds the stable proxy port and the
@@ -32,6 +33,29 @@ 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`).
 
+For boot/crash recovery, pass an explicit absolute `--config` and all three
+release options together. Rollbridge validates every bootstrap input before it
+binds listeners or starts processes, then binds the proxy and activates that
+exact release through the normal deploy path: services,
+companions, the proxied process and health check, traffic switching, singletons,
+and service-template refresh. Only after activation succeeds does it expose the
+control socket, preventing another deployment from overlapping bootstrap. It
+then remains in the foreground with the normal signal behavior.
+
+Bootstrap paths must be absolute and normalized, the release path must be an
+accessible directory, and release id/revision values accept letters, numbers,
+dots, underscores, and hyphens (maximum 200 characters, beginning with a letter
+or number). Supplying only some bootstrap options, or an invalid value, exits
+non-zero before listeners start. Activation failure emits a structured
+`bootstrap activation failed` event, cleans up processes owned by that attempt,
+and exits non-zero without exposing the control socket or inventing an active
+release. `statePath` entries from a previous daemon remain advisory orphans:
+bootstrap never runs recovery and never signals those processes, and retains
+their live PID records in `statePath` for explicit recovery.
+
+With no release options, daemon behavior is unchanged: it starts listener-only
+and waits for control-socket deployments.
+
 ## `ensure-daemon`
 
 ```

package/package.json

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

package/src/cli.js

@@ -30,12 +30,16 @@ export async function runCli(argv) {
   program
     .command("daemon")
     .option("-c, --config <path>", "Config file path (defaults to rollbridge.js)")
+    .option("--release-path <path>", "Bootstrap release path (requires --config, --release-id, and --revision)")
+    .option("--release-id <id>", "Bootstrap release id (requires --config, --release-path, and --revision)")
+    .option("--revision <sha>", "Bootstrap revision (requires --config, --release-path, and --release-id)")
     .action(async (options) => {
+      const bootstrap = await validateDaemonBootstrapOptions(options)
       const configPath = await resolveConfigPath(options.config)
       const config = await loadConfig(configPath)
       const daemon = new RollbridgeDaemon({config, configPath})
 
-      await daemon.start()
+      await daemon.start({exposeControl: !bootstrap})
 
       const shutdown = async () => {
         await daemon.shutdown()
@@ -44,6 +48,18 @@ export async function runCli(argv) {
 
       process.once("SIGINT", () => { void shutdown() })
       process.once("SIGTERM", () => { void shutdown() })
+
+      if (bootstrap) {
+        try {
+          await daemon.deploy(bootstrap)
+          await daemon.exposeControl()
+        } catch {
+          daemon.logger("bootstrap activation failed", {releaseId: bootstrap.releaseId, status: "error"})
+          await daemon.shutdown()
+          process.exitCode = 1
+          return
+        }
+      }
     })
 
   program
@@ -696,6 +712,49 @@ async function validateConfigFile(configPath) {
   }
 }
 
+/**
+ * Validates the daemon's optional all-or-nothing bootstrap release interface before
+ * config loading or listener startup.
+ * @param {{config?: string, releaseId?: string, releasePath?: string, revision?: string}} options - Daemon CLI options.
+ * @returns {Promise<{releaseId: string, releasePath: string, revision: string} | undefined>} Validated bootstrap metadata.
+ */
+async function validateDaemonBootstrapOptions(options) {
+  const bootstrapValues = [options.releasePath, options.releaseId, options.revision]
+  const bootstrapRequested = bootstrapValues.some((value) => value !== undefined)
+
+  if (!bootstrapRequested) return undefined
+
+  if (!options.config || bootstrapValues.some((value) => value === undefined)) {
+    throw new Error("Daemon bootstrap options --config, --release-path, --release-id, and --revision must be provided together.")
+  }
+
+  if (!path.isAbsolute(options.config)) throw new Error("Daemon bootstrap --config must be an absolute path.")
+  if (path.normalize(options.config) !== options.config) throw new Error("Daemon bootstrap --config must be normalized and must not contain unsafe traversal segments.")
+  if (!path.isAbsolute(/** @type {string} */ (options.releasePath))) throw new Error("Daemon bootstrap --release-path must be an absolute path.")
+  if (path.normalize(/** @type {string} */ (options.releasePath)) !== options.releasePath) throw new Error("Daemon bootstrap --release-path must be normalized and must not contain unsafe traversal segments.")
+
+  const releaseId = /** @type {string} */ (options.releaseId)
+  const revision = /** @type {string} */ (options.revision)
+  const safeIdentifier = /^[A-Za-z0-9][A-Za-z0-9._-]{0,199}$/
+
+  if (!safeIdentifier.test(releaseId)) throw new Error("Daemon bootstrap --release-id must be a non-empty safe identifier containing only letters, numbers, dots, underscores, and hyphens.")
+  if (!safeIdentifier.test(revision)) throw new Error("Daemon bootstrap --revision must be a non-empty safe identifier containing only letters, numbers, dots, underscores, and hyphens.")
+
+  let releaseStat
+
+  try {
+    releaseStat = await fsPromises.stat(/** @type {string} */ (options.releasePath))
+  } catch (error) {
+    const reason = error instanceof Error ? error.message : String(error)
+
+    throw new Error(`Daemon bootstrap --release-path is not accessible: ${reason}`, {cause: error})
+  }
+
+  if (!releaseStat.isDirectory()) throw new Error("Daemon bootstrap --release-path must name a directory.")
+
+  return {releaseId, releasePath: /** @type {string} */ (options.releasePath), revision}
+}
+
 /**
  * Starts a daemon when needed and waits until it accepts status commands.
  * @param {object} args - Options.

package/src/daemon.js

@@ -56,6 +56,7 @@ export default class RollbridgeDaemon {
     this.statePath = config.statePath
     this.persistTimer = /** @type {ReturnType<typeof setInterval> | undefined} */ (undefined)
     this.pendingWrite = /** @type {Promise<void> | undefined} */ (undefined)
+    this.startingReleases = /** @type {Set<ReleaseGroup>} */ (new Set())
     // Still-alive managed processes left by a previous daemon (from statePath), captured at
     // startup and surfaced in status(). The daemon cannot re-manage them, only report them.
     this.orphans = /** @type {{id: string, pid: number, releaseId: string | null}[]} */ ([])
@@ -63,11 +64,29 @@ export default class RollbridgeDaemon {
     this.proxy.on("error", (error, req, res) => this.onProxyError(error, req, res))
   }
 
-  /** @returns {Promise<void>} Starts proxy and control listeners. */
-  async start() {
+  /**
+   * Starts daemon listeners.
+   * @param {{exposeControl?: boolean}} [options] - Whether to expose the control socket immediately.
+   * @returns {Promise<void>} Resolves when the requested listeners are ready.
+   */
+  async start({exposeControl = true} = {}) {
     await this.reportOrphans()
     await this.startProxy()
+    if (exposeControl) await this.exposeControl()
+  }
+
+  /** @returns {Promise<void>} Exposes control commands and begins periodic state persistence. */
+  async exposeControl() {
+    if (this.stopping) throw new Error("Rollbridge is shutting down")
+
     await this.startControlServer()
+
+    if (this.stopping) {
+      await this.closeServer(this.controlServer)
+      await fs.rm(this.config.control.path, {force: true})
+      throw new Error("Rollbridge is shutting down")
+    }
+
     this.startStatePersistence()
   }
 
@@ -334,19 +353,26 @@ export default class RollbridgeDaemon {
       releaseId: newReleaseId,
       releasePath,
       revision,
-      servicePorts: this.servicePorts
+      servicePorts: this.servicePorts,
+      shouldStart: () => !this.stopping
     })
 
     this.logger("deploy starting", {releaseId: newReleaseId, releasePath, revision})
     const startedServices = /** @type {string[]} */ ([])
 
+    this.startingReleases.add(release)
+
     try {
       await this.ensureServices(release, startedServices)
       await release.start()
+      if (this.stopping) throw new Error("Rollbridge is shutting down")
     } catch (error) {
       this.logger("deploy failed", {error: error instanceof Error ? error.message : String(error), releaseId: newReleaseId})
+      await release.stop()
       await this.stopStartedServices(startedServices)
       throw error
+    } finally {
+      this.startingReleases.delete(release)
     }
 
     const previousRelease = this.activeRelease
@@ -467,6 +493,7 @@ export default class RollbridgeDaemon {
     await release.allocatePorts()
 
     for (const processConfig of release.config.processes) {
+      if (this.stopping) throw new Error("Rollbridge is shutting down")
       if (processConfig.policy !== "service" || processConfig.deployStrategy === "handoff") continue
       if (this.services.has(processConfig.id)) continue
 
@@ -486,6 +513,8 @@ export default class RollbridgeDaemon {
         delete this.servicePorts[processConfig.id]
         throw error
       }
+
+      if (this.stopping) throw new Error("Rollbridge is shutting down")
     }
   }
 
@@ -532,12 +561,14 @@ export default class RollbridgeDaemon {
    */
   async replaceSingletons(release) {
     for (const processConfig of this.config.processes) {
+      if (this.stopping) throw new Error("Rollbridge is shutting down")
       if (processConfig.policy !== "singleton") continue
 
       const previous = this.singletons.get(processConfig.id)
 
       if (previous) {
         await previous.stop()
+        if (this.stopping) throw new Error("Rollbridge is shutting down")
       }
 
       const singleton = release.buildProcess(processConfig)
@@ -688,9 +719,7 @@ export default class RollbridgeDaemon {
     if (!this.statePath || this.stopping) return
 
     const statePath = this.statePath
-    // Drop the orphans view from the snapshot: it reflects a *previous* daemon's leftovers, not
-    // this daemon's own managed state, and is recomputed from the persisted processes on restart.
-    const {orphans: _orphans, ...status} = this.status()
+    const status = this.status()
     const snapshot = {...status, events: this.eventLog.recent(), persistedAt: new Date().toISOString()}
 
     // Serialize writes (and track the tail) so shutdown can wait for an in-flight write before
@@ -742,17 +771,24 @@ export default class RollbridgeDaemon {
     this.proxy.close()
     await Promise.allSettled([...this.services.values()].map((processInstance) => processInstance.stop()))
     await Promise.allSettled([...this.singletons.values()].map((processInstance) => processInstance.stop()))
+    await Promise.allSettled([...this.startingReleases].map((release) => release.stop()))
     await Promise.allSettled([...this.releases.values()].map((release) => release.stop()))
     await this.closeServer(this.proxyServer)
     await this.closeServer(this.controlServer)
     await fs.rm(this.config.control.path, {force: true})
 
-    // A clean shutdown leaves no orphans, so remove the state file rather than leaving stale
-    // pids. Wait for any in-flight write first so it can't recreate the file afterward (no new
-    // writes start: stopping is set and the persist timer is cleared above).
+    // Wait for any in-flight write first so it can't recreate or overwrite the final state (no
+    // new writes start: stopping is set and the persist timer is cleared above). Prior-daemon
+    // orphans are not owned by this daemon, so retain their records until they are confirmed gone.
     if (this.statePath) {
       if (this.pendingWrite) await this.pendingWrite
-      await clearState(this.statePath)
+      const orphans = this.orphans.filter((orphan) => isProcessAlive(orphan.pid))
+
+      if (orphans.length > 0) {
+        await writeState(this.statePath, {activeReleaseId: null, orphans, releases: [], services: [], singletons: []})
+      } else {
+        await clearState(this.statePath)
+      }
     }
   }
 

package/src/release-group.js

@@ -40,8 +40,9 @@ export default class ReleaseGroup extends EventEmitter {
    * @param {string} args.releasePath - Release path.
    * @param {string | undefined} args.revision - Revision.
    * @param {Record<string, number>} [args.servicePorts] - Ports already owned by daemon-wide services.
+   * @param {() => boolean} [args.shouldStart] - Whether bootstrap may create another process.
    */
-  constructor({config, logger, releaseId, releasePath, revision, servicePorts = {}}) {
+  constructor({config, logger, releaseId, releasePath, revision, servicePorts = {}, shouldStart = () => true}) {
     super()
 
     this.config = config
@@ -57,6 +58,7 @@ export default class ReleaseGroup extends EventEmitter {
     this.nonBlockingDrainIds = /** @type {Set<string>} */ (new Set())
     this.ports = /** @type {Record<string, number>} */ ({})
     this.servicePorts = servicePorts
+    this.shouldStart = shouldStart
     this.portsAllocated = false
     this.drainStartedAt = /** @type {string | undefined} */ (undefined)
     this.activatedAt = /** @type {string | undefined} */ (undefined)
@@ -72,6 +74,8 @@ export default class ReleaseGroup extends EventEmitter {
 
       for (const processConfig of this.releaseProcessStartOrder()) {
         for (let index = 0; index < processConfig.replicas; index += 1) {
+          if (!this.shouldStart()) throw new Error("Rollbridge is shutting down")
+
           const instanceId = replicaInstanceId(processConfig, index)
           const processInstance = this.buildProcess(processConfig, {count: processConfig.replicas, index, instanceId})
 
@@ -87,6 +91,8 @@ export default class ReleaseGroup extends EventEmitter {
             host: this.config.proxy.upstreamHost,
             port: this.ports[processConfig.id]
           })
+
+          if (!this.shouldStart()) throw new Error("Rollbridge is shutting down")
         }
       }
     } catch (error) {

package/src/state-store.js

@@ -86,6 +86,14 @@ export function liveProcesses(state, alive = isProcessAlive) {
   try {
     const snapshot = /** @type {import("./daemon.js").DaemonStatus} */ (state)
 
+    if (Array.isArray(snapshot.orphans)) {
+      for (const orphan of snapshot.orphans) {
+        if (typeof orphan.id === "string" && typeof orphan.pid === "number" && (typeof orphan.releaseId === "string" || orphan.releaseId === null) && alive(orphan.pid)) {
+          live.push({id: orphan.id, pid: orphan.pid, releaseId: orphan.releaseId})
+        }
+      }
+    }
+
     for (const release of snapshot.releases) {
       for (const process of release.processes) {
         if (typeof process.pid === "number" && alive(process.pid)) live.push({id: process.id, pid: process.pid, releaseId: release.releaseId})

package/test/daemon-bootstrap.test.js

@@ -0,0 +1,396 @@
+// @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 {fileURLToPath} from "node:url"
+import {sendControlCommand} from "../src/control-client.js"
+import {isProcessAlive, liveProcesses, readState, writeState} from "../src/state-store.js"
+
+const currentDir = path.dirname(fileURLToPath(import.meta.url))
+const binPath = path.join(currentDir, "..", "bin", "rollbridge")
+const dummyAppPath = path.join(currentDir, "fixtures", "dummy-app.js")
+
+test("daemon bootstrap requires complete, safe, absolute inputs before binding listeners", async (t) => {
+  const cases = [
+    {args: ["--config", "CONFIG", "--release-path", "RELEASE", "--release-id", "v1"], message: /must be provided together/},
+    {args: ["--config", "relative/config.js", "--release-path", "RELEASE", "--release-id", "v1", "--revision", "abc123"], message: /--config must be an absolute path/},
+    {args: ["--config", "CONFIG", "--release-path", "relative/release", "--release-id", "v1", "--revision", "abc123"], message: /--release-path must be an absolute path/},
+    {args: ["--config", "CONFIG", "--release-path", "RELEASE", "--release-id", "unsafe id", "--revision", "abc123"], message: /--release-id/},
+    {args: ["--config", "CONFIG", "--release-path", "RELEASE", "--release-id", "v1", "--revision", "unsafe revision"], message: /--revision/}
+  ]
+
+  for (const testCase of cases) {
+    await t.test(testCase.message.source, async () => {
+      const fixture = await createFixture()
+      const args = testCase.args.map((arg) => arg === "CONFIG" ? fixture.configPath : arg === "RELEASE" ? fixture.root : arg)
+
+      try {
+        const result = await runDaemon(args)
+
+        assert.notEqual(result.code, 0)
+        assert.match(result.stderr, testCase.message)
+        await assert.rejects(() => fs.stat(fixture.socketPath), {code: "ENOENT"})
+      } finally {
+        await fs.rm(fixture.root, {force: true, recursive: true})
+      }
+    })
+  }
+})
+
+test("daemon bootstrap activates the exact release through the foreground daemon", async () => {
+  const fixture = await createFixture()
+  const child = spawnDaemon(fixture, {releaseId: "release-42", revision: "abc123"})
+
+  try {
+    await waitForLog(child, "control socket listening")
+    const status = await sendControlCommand({command: {command: "status"}, path: fixture.socketPath})
+    const activeRelease = assertRelease(status, "release-42")
+
+    assert.equal(activeRelease.releasePath, fixture.root)
+    assert.equal(activeRelease.revision, "abc123")
+    assert.ok(status.proxy && typeof status.proxy === "object" && !Array.isArray(status.proxy) && typeof status.proxy.port === "number")
+    assert.equal((await fetch(`http://127.0.0.1:${status.proxy.port}/release`).then((response) => response.text())).trim(), "release-42")
+
+    child.kill("SIGTERM")
+    assert.equal((await once(child, "exit"))[0], 0)
+  } finally {
+    if (child.exitCode === null) child.kill("SIGKILL")
+    await fs.rm(fixture.root, {force: true, recursive: true})
+  }
+})
+
+test("daemon bootstrap does not expose control deploys until activation completes", async () => {
+  const fixture = await createFixture({healthGate: true, healthTimeoutMs: 60000})
+  const started = waitForFile(fixture.startedPath)
+  const child = spawnDaemon(fixture, {releaseId: "bootstrap-release", revision: "bootstrap123"})
+
+  try {
+    await started
+    await assert.rejects(() => fs.stat(fixture.socketPath), {code: "ENOENT"})
+
+    await fs.writeFile(fixture.healthGatePath, "ready\n")
+    await waitForLog(child, "control socket listening")
+
+    const status = await sendControlCommand({command: {command: "status"}, path: fixture.socketPath})
+
+    assert.equal(status.activeReleaseId, "bootstrap-release")
+    assert.ok(Array.isArray(status.releases))
+    assert.equal(status.releases.length, 1)
+    assertRelease(status, "bootstrap-release")
+
+    child.kill("SIGTERM")
+    assert.equal((await once(child, "exit"))[0], 0)
+  } finally {
+    if (child.exitCode === null) child.kill("SIGKILL")
+    await fs.rm(fixture.root, {force: true, recursive: true})
+  }
+})
+
+test("plain daemon startup remains listener-only with no active release", async () => {
+  const fixture = await createFixture()
+  const child = spawn(process.execPath, [binPath, "daemon", "--config", fixture.configPath], {stdio: ["pipe", "pipe", "pipe"]})
+
+  try {
+    await waitForLog(child, "control socket listening")
+    const status = await sendControlCommand({command: {command: "status"}, path: fixture.socketPath})
+
+    assert.equal(status.activeReleaseId, null)
+    assert.deepEqual(status.releases, [])
+
+    child.kill("SIGTERM")
+    assert.equal((await once(child, "exit"))[0], 0)
+  } finally {
+    if (child.exitCode === null) child.kill("SIGKILL")
+    await fs.rm(fixture.root, {force: true, recursive: true})
+  }
+})
+
+test("SIGTERM during bootstrap activation follows the daemon shutdown path", async () => {
+  const fixture = await createFixture({healthPath: "/never-ready", healthTimeoutMs: 60000})
+  const started = waitForFile(fixture.startedPath)
+  const child = spawnDaemon(fixture, {releaseId: "slow-release", revision: "slow123"})
+
+  try {
+    const managedPid = Number(await started)
+    child.kill("SIGTERM")
+
+    const [code, signal] = await once(child, "exit")
+
+    assert.equal(code, 0)
+    assert.equal(signal, null)
+    assert.equal(await fs.readFile(fixture.stoppedPath, "utf8"), String(managedPid))
+    await assert.rejects(() => fs.stat(fixture.socketPath), {code: "ENOENT"})
+  } finally {
+    if (child.exitCode === null && child.signalCode === null) child.kill("SIGKILL")
+    await fs.rm(fixture.root, {force: true, recursive: true})
+  }
+})
+
+test("SIGTERM during multi-process bootstrap owns every process started after shutdown begins", async () => {
+  const fixture = await createFixture({multiProcessSignal: true})
+  const shutdownStarted = waitForLifecycleEvent(fixture.lifecyclePath, (event) => event.event === "shutdown")
+  const child = spawnDaemon(fixture, {releaseId: "multi-release", revision: "multi123"})
+  let output = ""
+
+  child.stdout.setEncoding("utf8").on("data", (chunk) => { output += chunk })
+
+  try {
+    await shutdownStarted
+    await fs.writeFile(fixture.gatePath, "continue\n")
+    const [code, signal] = await once(child, "exit")
+    const events = (await fs.readFile(fixture.lifecyclePath, "utf8")).trim().split("\n").map((line) => JSON.parse(line))
+    const shutdownIndex = events.findIndex((event) => event.event === "shutdown")
+    const startedAfterShutdown = events.slice(shutdownIndex + 1).filter((event) => event.event === "started")
+    const records = output.trim().split("\n").filter(Boolean).map((line) => JSON.parse(line))
+    const recordedPids = new Set(records.filter((record) => record.message === "process started").map((record) => record.data?.pid))
+
+    assert.equal(code, 0)
+    assert.equal(signal, null)
+    assert.notEqual(shutdownIndex, -1)
+    assert.ok(startedAfterShutdown.length > 0, `fixture must start a later bootstrap process after triggering shutdown: ${JSON.stringify(events)}`)
+    assert.deepEqual(startedAfterShutdown.filter((event) => !recordedPids.has(event.pid)), [])
+    for (const event of startedAfterShutdown) assert.equal(isProcessAlive(event.pid), false, `expected process ${event.pid} to be stopped before daemon exit`)
+  } finally {
+    if (child.exitCode === null && child.signalCode === null) child.kill("SIGKILL")
+
+    try {
+      const events = (await fs.readFile(fixture.lifecyclePath, "utf8")).trim().split("\n").filter(Boolean).map((line) => JSON.parse(line))
+
+      for (const event of events) {
+        if (event.event === "started" && isProcessAlive(event.pid)) process.kill(-event.pid, "SIGKILL")
+      }
+    } catch {
+      // The fixture may exit before creating its lifecycle log.
+    }
+
+    await fs.rm(fixture.root, {force: true, recursive: true})
+  }
+})
+
+test("failed daemon bootstrap reports a structured failure, cleans its processes, and exits non-zero", async () => {
+  const fixture = await createFixture({healthPath: "/never-ready", healthTimeoutMs: 100})
+
+  try {
+    const result = await runDaemon([
+      "--config", fixture.configPath,
+      "--release-path", fixture.root,
+      "--release-id", "bad-release",
+      "--revision", "bad123"
+    ])
+    const records = result.output.split("\n").filter(Boolean).map((line) => JSON.parse(line))
+    const failure = records.find((record) => record.message === "bootstrap activation failed")
+
+    assert.notEqual(result.code, 0)
+    assert.deepEqual(failure?.data, {releaseId: "bad-release", status: "error"})
+    assert.ok(records.some((record) => record.message === "release startup process status" && record.data?.phase === "after cleanup" && record.data?.state === "stopped"))
+    await assert.rejects(() => fs.stat(fixture.socketPath), {code: "ENOENT"})
+  } finally {
+    await fs.rm(fixture.root, {force: true, recursive: true})
+  }
+})
+
+test("daemon bootstrap reports but does not kill a live process from statePath", async () => {
+  const fixture = await createFixture({persistState: true})
+  const leftover = spawn(process.execPath, ["-e", "setInterval(() => {}, 1000)"], {stdio: "ignore"})
+
+  await once(leftover, "spawn")
+  await writeState(fixture.statePath, {
+    activeReleaseId: "previous",
+    releases: [{processes: [{id: "worker", pid: leftover.pid}], releaseId: "previous"}],
+    services: [],
+    singletons: []
+  })
+
+  const child = spawnDaemon(fixture, {releaseId: "recovered", revision: "def456"})
+
+  try {
+    await waitForLog(child, "control socket listening")
+    const status = await sendControlCommand({command: {command: "status"}, path: fixture.socketPath})
+
+    assert.ok(leftover.pid !== undefined && isProcessAlive(leftover.pid))
+    assert.deepEqual(status.orphans, [{id: "worker", pid: leftover.pid, releaseId: "previous"}])
+
+    child.kill("SIGTERM")
+    await once(child, "exit")
+
+    assert.deepEqual(liveProcesses(await readState(fixture.statePath)), [{id: "worker", pid: leftover.pid, releaseId: "previous"}])
+  } finally {
+    if (child.exitCode === null) child.kill("SIGKILL")
+    leftover.kill("SIGKILL")
+    await fs.rm(fixture.root, {force: true, recursive: true})
+  }
+})
+
+test("failed daemon bootstrap preserves prior live process records in statePath", async () => {
+  const fixture = await createFixture({healthPath: "/never-ready", healthTimeoutMs: 100, persistState: true})
+  const leftover = spawn(process.execPath, ["-e", "setInterval(() => {}, 1000)"], {stdio: "ignore"})
+
+  await once(leftover, "spawn")
+  await writeState(fixture.statePath, {
+    activeReleaseId: "previous",
+    releases: [{processes: [{id: "worker", pid: leftover.pid}], releaseId: "previous"}],
+    services: [],
+    singletons: []
+  })
+
+  try {
+    const result = await runDaemon([
+      "--config", fixture.configPath,
+      "--release-path", fixture.root,
+      "--release-id", "bad-release",
+      "--revision", "bad123"
+    ])
+
+    assert.notEqual(result.code, 0)
+    assert.deepEqual(liveProcesses(await readState(fixture.statePath)), [{id: "worker", pid: leftover.pid, releaseId: "previous"}])
+  } finally {
+    leftover.kill("SIGKILL")
+    await fs.rm(fixture.root, {force: true, recursive: true})
+  }
+})
+
+/**
+ * @param {{healthGate?: boolean, healthPath?: string, healthTimeoutMs?: number, multiProcessSignal?: boolean, persistState?: boolean}} [options] - Fixture options.
+ * @returns {Promise<{configPath: string, gatePath: string, healthGatePath: string, lifecyclePath: string, root: string, socketPath: string, startedPath: string, statePath: string, stoppedPath: string}>} Fixture paths.
+ */
+async function createFixture({healthGate = false, healthPath = "/ping", healthTimeoutMs = 1000, multiProcessSignal = false, persistState = false} = {}) {
+  const root = await fs.mkdtemp(path.join(os.tmpdir(), "rollbridge-bootstrap-"))
+  const socketPath = path.join(root, "control.sock")
+  const statePath = path.join(root, "state.json")
+  const startedPath = path.join(root, "started.pid")
+  const stoppedPath = path.join(root, "stopped.pid")
+  const lifecyclePath = path.join(root, "lifecycle.jsonl")
+  const gatePath = path.join(root, "continue.fifo")
+  const healthGatePath = path.join(root, "health-ready")
+  const configPath = path.join(root, "rollbridge.js")
+  const command = `${JSON.stringify(process.execPath)} ${JSON.stringify(dummyAppPath)}`
+  const lifecycleEnv = {ROLLBRIDGE_TEST_LIFECYCLE_PATH: lifecyclePath}
+  const webEnv = {
+    ROLLBRIDGE_TEST_STARTED_PATH: startedPath,
+    ROLLBRIDGE_TEST_STOPPED_PATH: stoppedPath,
+    ...(healthGate ? {ROLLBRIDGE_TEST_HEALTH_GATE_PATH: healthGatePath} : {})
+  }
+  const config = {
+    application: "bootstrap-test",
+    control: {path: socketPath},
+    processes: multiProcessSignal ? [
+      {command: `trap '' TERM; printf '%s\\n' '{"event":"shutdown"}' >> ${JSON.stringify(lifecyclePath)}; kill -TERM "$ROLLBRIDGE_TEST_DAEMON_PID"; printf '{"event":"started","pid":%s,"processId":"database","replicaIndex":"0"}\\n' "$$" >> ${JSON.stringify(lifecyclePath)}; read ignored < ${JSON.stringify(gatePath)}`, env: lifecycleEnv, id: "database", policy: "service"},
+      {command: `exec ${command}`, env: lifecycleEnv, id: "worker", policy: "companion", replicas: 2},
+      {command: `exec ${command}`, env: lifecycleEnv, health: {path: healthPath, timeoutMs: healthTimeoutMs}, id: "web", policy: "proxied", port: {from: 0, to: 0}}
+    ] : [{command, env: webEnv, health: {path: healthPath, timeoutMs: healthTimeoutMs}, id: "web", policy: "proxied", port: {from: 0, to: 0}}],
+    proxy: {host: "127.0.0.1", port: 0},
+    ...(persistState ? {statePath} : {})
+  }
+
+  const setup = multiProcessSignal ? "process.env.ROLLBRIDGE_TEST_DAEMON_PID = String(process.pid)\n" : ""
+
+  if (multiProcessSignal) {
+    const fifo = spawn("mkfifo", [gatePath])
+    const [code] = await once(fifo, "exit")
+
+    assert.equal(code, 0)
+  }
+
+  await fs.writeFile(configPath, `${setup}module.exports = ${JSON.stringify(config, null, 2)}\n`)
+  return {configPath, gatePath, healthGatePath, lifecyclePath, root, socketPath, startedPath, statePath, stoppedPath}
+}
+
+/**
+ * @param {string} filePath - JSON-lines event path.
+ * @param {(event: Record<string, import("../src/json.js").JsonValue>) => boolean} matches - Event predicate.
+ * @returns {Promise<Record<string, import("../src/json.js").JsonValue>>} First matching event.
+ */
+async function waitForLifecycleEvent(filePath, matches) {
+  const watcher = fs.watch(path.dirname(filePath))
+
+  try {
+    for await (const event of watcher) {
+      if (event.filename !== path.basename(filePath)) continue
+
+      const records = (await fs.readFile(filePath, "utf8")).trim().split("\n").filter(Boolean).map((line) => JSON.parse(line))
+      const match = records.find(matches)
+
+      if (match) return match
+    }
+  } finally {
+    await watcher.return?.()
+  }
+
+  throw new Error(`File watcher ended before a matching event was written to ${filePath}`)
+}
+
+/**
+ * @param {string} filePath - File whose creation is the synchronization point.
+ * @returns {Promise<string>} File contents once created.
+ */
+async function waitForFile(filePath) {
+  const watcher = fs.watch(path.dirname(filePath))
+
+  try {
+    for await (const event of watcher) {
+      if (event.filename === path.basename(filePath)) return await fs.readFile(filePath, "utf8")
+    }
+  } finally {
+    await watcher.return?.()
+  }
+
+  throw new Error(`File watcher ended before ${filePath} was created`)
+}
+
+/**
+ * @param {{configPath: string, root: string}} fixture - Fixture paths.
+ * @param {{releaseId: string, revision: string}} release - Bootstrap metadata.
+ * @returns {import("node:child_process").ChildProcessWithoutNullStreams} Spawned daemon.
+ */
+function spawnDaemon(fixture, release) {
+  return spawn(process.execPath, [binPath, "daemon", "--config", fixture.configPath, "--release-path", fixture.root, "--release-id", release.releaseId, "--revision", release.revision], {stdio: ["pipe", "pipe", "pipe"]})
+}
+
+/**
+ * @param {string[]} args - Daemon arguments.
+ * @returns {Promise<{code: number | null, output: string, stderr: string}>} Completed process result.
+ */
+async function runDaemon(args) {
+  const child = spawn(process.execPath, [binPath, "daemon", ...args], {stdio: ["ignore", "pipe", "pipe"]})
+  let output = ""
+  let stderr = ""
+
+  child.stdout.setEncoding("utf8").on("data", (chunk) => { output += chunk })
+  child.stderr.setEncoding("utf8").on("data", (chunk) => { stderr += chunk })
+  const [code] = await once(child, "exit")
+
+  return {code, output, stderr}
+}
+
+/**
+ * @param {import("node:child_process").ChildProcessWithoutNullStreams} child - Spawned daemon.
+ * @param {string} message - Structured log message to await.
+ * @returns {Promise<void>} Resolves after the message is observed.
+ */
+async function waitForLog(child, message) {
+  child.stdout.setEncoding("utf8")
+
+  for await (const chunk of child.stdout) {
+    if (String(chunk).includes(`"message":"${message}"`)) return
+  }
+
+  throw new Error(`Daemon exited before logging ${message}`)
+}
+
+/**
+ * @param {Record<string, import("../src/json.js").JsonValue>} status - Daemon status.
+ * @param {string} releaseId - Expected release id.
+ * @returns {Record<string, import("../src/json.js").JsonValue>} Matching release status.
+ */
+function assertRelease(status, releaseId) {
+  assert.ok(Array.isArray(status.releases))
+  const release = status.releases.find((candidate) => candidate && typeof candidate === "object" && "releaseId" in candidate && candidate.releaseId === releaseId)
+
+  assert.ok(release && typeof release === "object" && !Array.isArray(release))
+  return release
+}

package/test/fixtures/dummy-app.js

@@ -1,6 +1,7 @@
 // @ts-check
 
 import crypto from "node:crypto"
+import fs from "node:fs"
 import http from "node:http"
 
 const port = Number(process.env.ROLLBRIDGE_PORT)
@@ -8,9 +9,13 @@ const releaseId = process.env.ROLLBRIDGE_RELEASE_ID || "unknown"
 const healthFails = releaseId.includes("bad")
 const sockets = new Set()
 
+if (process.env.ROLLBRIDGE_TEST_STARTED_PATH) {
+  fs.writeFileSync(process.env.ROLLBRIDGE_TEST_STARTED_PATH, String(process.pid))
+}
+
 const server = http.createServer((request, response) => {
   if (request.url === "/ping") {
-    if (healthFails) {
+    if (healthFails || (process.env.ROLLBRIDGE_TEST_HEALTH_GATE_PATH && !fs.existsSync(process.env.ROLLBRIDGE_TEST_HEALTH_GATE_PATH))) {
       response.writeHead(500, {"Content-Type": "application/json"})
       response.end(JSON.stringify({message: "bad release"}))
       return
@@ -59,6 +64,14 @@ server.on("upgrade", (request, socket) => {
 })
 
 process.on("SIGTERM", () => {
+  if (process.env.ROLLBRIDGE_TEST_LIFECYCLE_PATH) {
+    fs.appendFileSync(process.env.ROLLBRIDGE_TEST_LIFECYCLE_PATH, `${JSON.stringify({event: "stopped", pid: process.pid, processId: process.env.ROLLBRIDGE_PROCESS_ID, replicaIndex: process.env.ROLLBRIDGE_REPLICA_INDEX})}\n`)
+  }
+
+  if (process.env.ROLLBRIDGE_TEST_STOPPED_PATH) {
+    fs.writeFileSync(process.env.ROLLBRIDGE_TEST_STOPPED_PATH, String(process.pid))
+  }
+
   server.close(() => process.exit(0))
 
   if (sockets.size === 0) {
@@ -66,4 +79,14 @@ process.on("SIGTERM", () => {
   }
 })
 
-server.listen(port, "127.0.0.1")
+const recordStarted = () => {
+  if (process.env.ROLLBRIDGE_TEST_LIFECYCLE_PATH) {
+    fs.appendFileSync(process.env.ROLLBRIDGE_TEST_LIFECYCLE_PATH, `${JSON.stringify({event: "started", pid: process.pid, processId: process.env.ROLLBRIDGE_PROCESS_ID, replicaIndex: process.env.ROLLBRIDGE_REPLICA_INDEX})}\n`)
+  }
+}
+
+if (process.env.ROLLBRIDGE_PORT) {
+  server.listen(port, "127.0.0.1", recordStarted)
+} else {
+  recordStarted()
+}

package/test/package-metadata.test.js

@@ -1,12 +1,16 @@
 // @ts-check
 
 import assert from "node:assert/strict"
+import {execFile} from "node:child_process"
 import fs from "node:fs/promises"
+import os from "node:os"
 import path from "node:path"
 import test from "node:test"
 import {fileURLToPath} from "node:url"
+import {promisify} from "node:util"
 
 const repoRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..")
+const execFileAsync = promisify(execFile)
 
 test("package.json declares publish metadata", async () => {
   const pkg = JSON.parse(await fs.readFile(path.join(repoRoot, "package.json"), "utf8"))
@@ -27,3 +31,38 @@ test("a LICENSE file matching the declared license exists", async () => {
   assert.match(license, /MIT License/)
   assert.match(license, /Copyright \(c\) \d{4} kaspernj/)
 })
+
+test("package manifest excludes unexpected operational and coverage files", async (t) => {
+  const fixtureRoot = await fs.mkdtemp(path.join(os.tmpdir(), "rollbridge-pack-"))
+  t.after(() => fs.rm(fixtureRoot, {force: true, recursive: true}))
+
+  await fs.cp(repoRoot, fixtureRoot, {
+    filter: (source) => {
+      const relative = path.relative(repoRoot, source)
+      return relative !== ".git" && relative !== "node_modules" && relative !== "tmp"
+    },
+    recursive: true,
+  })
+
+  const unexpectedTmpPath = path.join(fixtureRoot, "tmp", "worker-control", "unexpected-transcript.jsonl")
+  const unexpectedCoveragePath = path.join(fixtureRoot, "coverage", "unexpected.txt")
+  await Promise.all([
+    fs.mkdir(path.dirname(unexpectedTmpPath), {recursive: true}),
+    fs.mkdir(path.dirname(unexpectedCoveragePath), {recursive: true}),
+  ])
+  await Promise.all([
+    fs.writeFile(unexpectedTmpPath, '{"operational":"state"}\n'),
+    fs.writeFile(unexpectedCoveragePath, "unexpected coverage output\n"),
+  ])
+
+  const {stdout} = await execFileAsync("npm", ["pack", "--dry-run", "--json"], {cwd: fixtureRoot})
+  /** @type {Array<{path: string}>} */
+  const packageFiles = JSON.parse(stdout)[0].files
+  const packagePaths = packageFiles.map((file) => file.path)
+
+  for (const requiredPath of ["LICENSE", "README.md", "bin/rollbridge", "package.json", "src/cli.js"]) {
+    assert.ok(packagePaths.includes(requiredPath), `expected package to include ${requiredPath}`)
+  }
+  assert.ok(!packagePaths.some((packagePath) => packagePath === "tmp" || packagePath.startsWith("tmp/")))
+  assert.ok(!packagePaths.some((packagePath) => packagePath === "coverage" || packagePath.startsWith("coverage/")))
+})