rollbridge 0.1.17 → 0.1.19

package/README.md

@@ -408,7 +408,8 @@ 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
+  --release-id 20260813090000 --revision abc123 \
+  --boot-attestation sha256:0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef
 ```
 
 The four bootstrap inputs are all-or-nothing and use absolute config/release
@@ -419,6 +420,14 @@ 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.
 
+External supervisors may add `--boot-attestation` with exactly `sha256:` plus
+64 lowercase hexadecimal characters. After successful activation, `rollbridge
+status` echoes the opaque, non-secret value under `bootstrap.attestation`
+alongside the exact release id/path/revision. Listener-only and detached ensured
+daemons omit `bootstrap`, so a supervisor can distinguish a newly accepted
+foreground owner from a stale daemon without Rollbridge interpreting the token.
+See [`docs/cli.md`](docs/cli.md#daemon) for the complete contract.
+
 Start the daemon only when it is not already running:
 
 ```bash
@@ -500,6 +509,12 @@ Shut down the daemon and managed processes:
 rollbridge shutdown --config rollbridge.js
 ```
 
+A successful shutdown response is emitted only after the targeted control
+endpoint has stopped accepting connections and been removed, owned processes
+and the proxy have stopped, and persistent state cleanup has finished. It is
+therefore safe to start or ensure a replacement daemon immediately, without a
+delay or retry loop. Cleanup failure or an already-missing daemon exits non-zero.
+
 Prepare a first Rollbridge deploy by recovering Rollbridge-managed orphans and
 stopping configured legacy processes:
 

package/docs/cli.md

@@ -24,7 +24,8 @@ process-policy details.
 
 ```
 rollbridge daemon [--config <path>]
-                  [--release-path <path> --release-id <id> --revision <sha>]
+                  [--release-path <path> --release-id <id> --revision <sha>
+                   [--boot-attestation <sha256:digest>]]
 ```
 
 Runs the supervisor in the foreground: binds the stable proxy port and the
@@ -53,6 +54,13 @@ 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.
 
+`--boot-attestation` is an optional, non-secret opaque ownership token for an
+external supervisor. Its canonical format is exactly `sha256:` followed by 64
+lowercase hexadecimal characters. It is accepted only with the complete
+known-release bootstrap tuple above and is never accepted by `ensure-daemon`.
+After successful activation, `status` echoes it unchanged in the bootstrap
+identity. Rollbridge does not calculate or interpret the digest.
+
 With no release options, daemon behavior is unchanged: it starts listener-only
 and waits for control-socket deployments.
 
@@ -174,6 +182,24 @@ Memory-supervised processes also report `rssBytes`, `memoryRestarts`,
 its runtime `format`, package `version`, content `digest`, and absolute `path`.
 `ensure-daemon` uses this attestation before reusing a responsive daemon.
 
+A foreground known-release daemon also reports the exact CLI bootstrap identity:
+
+```json
+{
+  "bootstrap": {
+    "releaseId": "20260813090000",
+    "releasePath": "/srv/app/releases/20260813090000/app",
+    "revision": "abc123",
+    "attestation": "sha256:0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef"
+  }
+}
+```
+
+`attestation` is omitted when the optional argument was not supplied. Ordinary
+listener-only daemons and detached daemons created by `ensure-daemon` omit the
+entire `bootstrap` object. External supervisors can therefore distinguish two
+otherwise identical foreground boots by comparing the opaque attestation.
+
 When [`statePath`](config.md#statepath) is configured, status also includes an
 `orphans` array: managed processes from a **previous** daemon that are still
 alive (`id`, `pid`, `releaseId`) — for example after the daemon restarted but its
@@ -266,7 +292,15 @@ rollbridge shutdown [--config <path>]
 
 Stops all managed processes (services, singletons, and releases), closes the
 proxy and control socket, removes the socket file, and prints
-`{"status": "success", "message": "shutdown"}`.
+`{"status": "success", "message": "shutdown"}`. The success response is a
+completion signal, not an early acknowledgement: before sending it, Rollbridge
+stops accepting new control connections, removes the targeted socket, finishes
+owned-process and proxy cleanup, and finalizes persistent state. A caller may
+immediately start or ensure a replacement daemon after the command returns.
+
+If cleanup fails, the command exits non-zero with the daemon's error instead of
+reporting success. Calling `shutdown` when no daemon owns the configured control
+socket also remains an explicit connection error.
 
 ## `validate`
 

package/package.json

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

package/src/cli.js

@@ -35,12 +35,13 @@ export async function runCli(argv) {
     .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)")
+    .option("--boot-attestation <digest>", "Opaque bootstrap ownership attestation (requires the complete bootstrap release tuple)")
     .action(async (options) => {
       const bootstrap = await validateDaemonBootstrapOptions(options)
       const configPath = await resolveConfigPath(options.config)
       const config = await loadConfig(configPath)
       const runtime = await loadDaemonRuntimeIdentity(process.env.ROLLBRIDGE_DAEMON_RUNTIME_MANIFEST)
-      const daemon = new RollbridgeDaemon({config, configPath, runtime})
+      const daemon = new RollbridgeDaemon({bootstrap, config, configPath, runtime})
 
       await daemon.start({exposeControl: !bootstrap})
 
@@ -720,13 +721,17 @@ 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.
+ * @param {{bootAttestation?: string, config?: string, releaseId?: string, releasePath?: string, revision?: string}} options - Daemon CLI options.
+ * @returns {Promise<{attestation?: string, 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 (options.bootAttestation !== undefined && !bootstrapRequested) {
+    throw new Error("Daemon --boot-attestation is accepted only with --config, --release-path, --release-id, and --revision.")
+  }
+
   if (!bootstrapRequested) return undefined
 
   if (!options.config || bootstrapValues.some((value) => value === undefined)) {
@@ -744,6 +749,7 @@ async function validateDaemonBootstrapOptions(options) {
 
   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.")
+  if (options.bootAttestation !== undefined && !/^sha256:[a-f0-9]{64}$/.test(options.bootAttestation)) throw new Error("Daemon bootstrap --boot-attestation must use the canonical sha256:<64 lowercase hex> format.")
 
   let releaseStat
 
@@ -757,7 +763,7 @@ async function validateDaemonBootstrapOptions(options) {
 
   if (!releaseStat.isDirectory()) throw new Error("Daemon bootstrap --release-path must name a directory.")
 
-  return {releaseId, releasePath: /** @type {string} */ (options.releasePath), revision}
+  return {attestation: options.bootAttestation, releaseId, releasePath: /** @type {string} */ (options.releasePath), revision}
 }
 
 /**

package/src/daemon.js

@@ -17,19 +17,22 @@ const STATE_PERSIST_INTERVAL_MS = 5000
 /**
  * @typedef {import("./json.js").JsonValue} JsonValue
  * @typedef {{releaseId?: string, releasePath: string, revision?: string}} DeployArgs
+ * @typedef {{attestation?: string, releaseId: string, releasePath: string, revision: string}} BootstrapIdentity
  * @typedef {{id: string, process: import("./managed-process.js").ManagedProcessStatus}} ProcessStatus
- * @typedef {{activeReleaseId: string | null, application: string, control: import("./config.js").ControlConfig, daemonRuntime: import("./daemon-runtime.js").DaemonRuntimeIdentity | undefined, orphans: {id: string, pid: number, releaseId: string | null}[], proxy: {host: string, port: number | undefined, upstreamHost: string}, releases: import("./release-group.js").ReleaseStatus[], services: ProcessStatus[], singletons: ProcessStatus[]}} DaemonStatus
+ * @typedef {{activeReleaseId: string | null, application: string, bootstrap: BootstrapIdentity | undefined, control: import("./config.js").ControlConfig, daemonRuntime: import("./daemon-runtime.js").DaemonRuntimeIdentity | undefined, orphans: {id: string, pid: number, releaseId: string | null}[], proxy: {host: string, port: number | undefined, upstreamHost: string}, releases: import("./release-group.js").ReleaseStatus[], services: ProcessStatus[], singletons: ProcessStatus[]}} DaemonStatus
  */
 
 export default class RollbridgeDaemon {
   /**
    * @param {object} args - Options.
+   * @param {BootstrapIdentity} [args.bootstrap] - Immutable known-release foreground bootstrap identity.
    * @param {import("./config.js").RollbridgeConfig} args.config - Rollbridge config.
    * @param {string} [args.configPath] - Config file path to reload before deploys.
    * @param {(message: string, data?: Record<string, JsonValue>) => void} [args.logger] - Logger.
    * @param {import("./daemon-runtime.js").DaemonRuntimeIdentity} [args.runtime] - Immutable daemon runtime identity.
    */
-  constructor({config, configPath, logger, runtime}) {
+  constructor({bootstrap, config, configPath, logger, runtime}) {
+    this.bootstrap = bootstrap ? {...bootstrap} : undefined
     this.config = config
     this.configPath = configPath
     this.runtime = runtime
@@ -53,11 +56,14 @@ export default class RollbridgeDaemon {
     this.proxy = httpProxy.createProxyServer({ws: true, xfwd: true})
     this.proxyServer = /** @type {http.Server | undefined} */ (undefined)
     this.controlServer = /** @type {net.Server | undefined} */ (undefined)
+    this.controlSockets = /** @type {Set<net.Socket>} */ (new Set())
     this.proxyPort = /** @type {number | undefined} */ (undefined)
     this.stopping = false
     this.statePath = config.statePath
     this.persistTimer = /** @type {ReturnType<typeof setInterval> | undefined} */ (undefined)
     this.pendingWrite = /** @type {Promise<void> | undefined} */ (undefined)
+    this.shutdownPromise = /** @type {Promise<void> | undefined} */ (undefined)
+    this.controlClosePromise = /** @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.
@@ -244,9 +250,17 @@ export default class RollbridgeDaemon {
    * @returns {void}
    */
   handleControlSocket(socket) {
+    this.controlSockets.add(socket)
     socket.setEncoding("utf8")
     let buffer = ""
 
+    socket.once("close", () => this.controlSockets.delete(socket))
+    socket.on("error", (error) => {
+      const code = error && typeof error === "object" && "code" in error && typeof error.code === "string" ? error.code : null
+
+      this.logger("control connection error", {code, error: error.message})
+    })
+
     socket.on("data", (chunk) => {
       buffer += chunk
       let newlineIndex = buffer.indexOf("\n")
@@ -266,22 +280,34 @@ export default class RollbridgeDaemon {
    * @returns {void}
    */
   handleControlLine(line, socket) {
-    this.executeControlLine(line)
-      .then((response) => socket.write(`${JSON.stringify({status: "success", ...response})}\n`))
+    const closesConnection = isShutdownControlLine(line)
+    const respond = (/** @type {Record<string, JsonValue>} */ response) => {
+      const payload = `${JSON.stringify(response)}\n`
+
+      if (closesConnection) {
+        socket.end(payload, () => socket.destroy())
+      } else if (!socket.destroyed) {
+        socket.write(payload)
+      }
+    }
+
+    this.executeControlLine(line, socket)
+      .then((response) => respond({status: "success", ...response}))
       .catch((error) => {
         this.logger("command failed", {error: error instanceof Error ? error.message : String(error)})
-        socket.write(`${JSON.stringify({
+        respond({
           error: error instanceof Error ? error.message : String(error),
           status: "error"
-        })}\n`)
+        })
       })
   }
 
   /**
    * @param {string} line - JSON command line.
+   * @param {net.Socket} [controlSocket] - Requesting control connection, used only for shutdown completion.
    * @returns {Promise<Record<string, JsonValue>>} Command response.
    */
-  async executeControlLine(line) {
+  async executeControlLine(line, controlSocket) {
     const command = JSON.parse(line)
 
     if (!command || typeof command !== "object") {
@@ -324,11 +350,10 @@ export default class RollbridgeDaemon {
     }
 
     if (commandName === "shutdown") {
-      setImmediate(() => {
-        this.shutdown().catch((error) => {
-          this.logger("shutdown failed", {error: error instanceof Error ? error.message : String(error)})
-        })
-      })
+      // Stop accepting new control connections before cleanup, but keep this requesting
+      // connection open as the completion channel. Waiting for all control connections here
+      // would deadlock: server.close() includes the socket awaiting this response.
+      await this.shutdown({completionSocket: controlSocket, waitForControlConnections: false})
 
       return {message: "shutdown"}
     }
@@ -760,30 +785,56 @@ export default class RollbridgeDaemon {
     }
   }
 
-  /** @returns {Promise<void>} Stops proxy, control socket, and child processes. */
-  async shutdown() {
-    if (this.stopping) return
+  /**
+   * Stops proxy, control socket, and child processes.
+   * @param {{completionSocket?: net.Socket, waitForControlConnections?: boolean}} [options] - Shutdown connection behavior.
+   * @returns {Promise<void>} Resolves when owned resources are stopped (and, by default, control connections close).
+   */
+  async shutdown({completionSocket, waitForControlConnections = true} = {}) {
+    if (!this.shutdownPromise) this.shutdownPromise = this.performShutdown(completionSocket)
+
+    await this.shutdownPromise
+    if (waitForControlConnections && this.controlClosePromise) await this.controlClosePromise
+  }
 
+  /**
+   * @param {net.Socket | undefined} completionSocket - Requester retained for the final response.
+   * @returns {Promise<void>} Retires listeners and cleans up every daemon-owned resource.
+   */
+  async performShutdown(completionSocket) {
     this.stopping = true
+    const cleanupErrors = /** @type {Error[]} */ ([])
+
+    // server.close() stops new connections synchronously. Unlink immediately afterward so a
+    // replacement can bind as soon as cleanup completes; existing connections remain usable for
+    // the shutdown completion/error response.
+    this.controlClosePromise = this.closeServer(this.controlServer)
+
+    for (const socket of this.controlSockets) {
+      if (socket !== completionSocket) socket.destroy()
+    }
+
+    await captureShutdownError(cleanupErrors, "control socket unlink", () => this.removeControlSocket())
 
     if (this.persistTimer) {
       clearInterval(this.persistTimer)
       this.persistTimer = undefined
     }
 
-    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})
+    await captureShutdownError(cleanupErrors, "proxy close", async () => this.proxy.close())
+    const stopResults = await Promise.allSettled([
+      ...[...this.services.values()].map((processInstance) => processInstance.stop()),
+      ...[...this.singletons.values()].map((processInstance) => processInstance.stop()),
+      ...[...this.startingReleases].map((release) => release.stop()),
+      ...[...this.releases.values()].map((release) => release.stop())
+    ])
+    await captureShutdownError(cleanupErrors, "proxy server close", () => this.closeServer(this.proxyServer))
 
     // 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) {
+    await captureShutdownError(cleanupErrors, "persistent state cleanup", async () => {
+      if (!this.statePath) return
       if (this.pendingWrite) await this.pendingWrite
       const orphans = this.orphans.filter((orphan) => isProcessAlive(orphan.pid))
 
@@ -792,7 +843,20 @@ export default class RollbridgeDaemon {
       } else {
         await clearState(this.statePath)
       }
+    })
+
+    const stopErrors = stopResults.filter((result) => result.status === "rejected").map((result) => result.reason)
+
+    if (stopErrors.length > 0) {
+      cleanupErrors.push(new AggregateError(stopErrors, `Shutdown failed to stop ${stopErrors.length} owned resource${stopErrors.length === 1 ? "" : "s"}.`))
     }
+
+    if (cleanupErrors.length > 0) throw new AggregateError(cleanupErrors, cleanupErrors.map((error) => error.message).join("; "))
+  }
+
+  /** @returns {Promise<void>} Removes the configured control socket path. */
+  async removeControlSocket() {
+    await fs.rm(this.config.control.path, {force: true})
   }
 
   /**
@@ -820,6 +884,7 @@ export default class RollbridgeDaemon {
     return {
       activeReleaseId: this.activeRelease ? this.activeRelease.releaseId : null,
       application: this.config.application,
+      bootstrap: this.bootstrap ? {...this.bootstrap} : undefined,
       control: {...this.config.control},
       daemonRuntime: this.runtime ? {...this.runtime} : undefined,
       orphans: [...this.orphans],
@@ -852,6 +917,37 @@ function stringOrUndefined(value) {
   return value
 }
 
+/**
+ * @param {string} line - Raw control line.
+ * @returns {boolean} Whether the line requests shutdown and needs a terminal response connection.
+ */
+function isShutdownControlLine(line) {
+  try {
+    const command = JSON.parse(line)
+
+    return Boolean(command && typeof command === "object" && command.command === "shutdown")
+  } catch {
+    return false
+  }
+}
+
+/**
+ * Runs one shutdown cleanup step and records a labeled failure without skipping later cleanup.
+ * @param {Error[]} errors - Accumulated cleanup errors.
+ * @param {string} label - Non-secret cleanup step name.
+ * @param {() => Promise<void>} operation - Cleanup operation.
+ * @returns {Promise<void>} Resolves after the operation succeeds or its failure is recorded.
+ */
+async function captureShutdownError(errors, label, operation) {
+  try {
+    await operation()
+  } catch (error) {
+    const reason = error instanceof Error ? error.message : String(error)
+
+    errors.push(new Error(`${label} failed: ${reason}`, {cause: error}))
+  }
+}
+
 const SECRET_BEARING_STATE_KEYS = new Set(["children", "command", "cwd", "env", "environment", "logs", "output"])
 
 /**

package/test/daemon-bootstrap.test.js

@@ -14,6 +14,8 @@ import {isProcessAlive, liveProcesses, readState, writeState} from "../src/state
 const currentDir = path.dirname(fileURLToPath(import.meta.url))
 const binPath = path.join(currentDir, "..", "bin", "rollbridge")
 const dummyAppPath = path.join(currentDir, "fixtures", "dummy-app.js")
+const firstAttestation = `sha256:${"a".repeat(64)}`
+const secondAttestation = `sha256:${"b".repeat(64)}`
 
 test("daemon bootstrap requires complete, safe, absolute inputs before binding listeners", async (t) => {
   const cases = [
@@ -23,7 +25,11 @@ test("daemon bootstrap requires complete, safe, absolute inputs before binding l
     {args: ["--config", "CONFIG", "--release-path", "RELEASE_UNNORMALIZED", "--release-id", "v1", "--revision", "abc123"], message: /--release-path must be normalized/},
     {args: ["--config", "CONFIG", "--release-path", "RELEASE_MISSING", "--release-id", "v1", "--revision", "abc123"], message: /--release-path is not accessible/},
     {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/}
+    {args: ["--config", "CONFIG", "--release-path", "RELEASE", "--release-id", "v1", "--revision", "unsafe revision"], message: /--revision/},
+    {args: ["--config", "CONFIG", "--boot-attestation", firstAttestation], message: /accepted only with/},
+    {args: ["--config", "CONFIG", "--release-path", "RELEASE", "--release-id", "v1", "--revision", "abc123", "--boot-attestation", `sha256:${"A".repeat(64)}`], message: /--boot-attestation/},
+    {args: ["--config", "CONFIG", "--release-path", "RELEASE", "--release-id", "v1", "--revision", "abc123", "--boot-attestation", `sha512:${"a".repeat(64)}`], message: /--boot-attestation/},
+    {args: ["--config", "CONFIG", "--release-path", "RELEASE", "--release-id", "v1", "--revision", "abc123", "--boot-attestation", `sha256:${"a".repeat(63)}`], message: /--boot-attestation/}
   ]
 
   for (const testCase of cases) {
@@ -43,6 +49,7 @@ test("daemon bootstrap requires complete, safe, absolute inputs before binding l
         assert.notEqual(result.code, 0)
         assert.match(result.stderr, testCase.message)
         await assert.rejects(() => fs.stat(fixture.socketPath), {code: "ENOENT"})
+        await assert.rejects(() => fs.stat(fixture.startedPath), {code: "ENOENT"})
       } finally {
         await fs.rm(fixture.root, {force: true, recursive: true})
       }
@@ -52,7 +59,7 @@ test("daemon bootstrap requires complete, safe, absolute inputs before binding l
 
 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"})
+  const child = spawnDaemon(fixture, {attestation: firstAttestation, releaseId: "release-42", revision: "abc123"})
 
   try {
     await waitForLog(child, "control socket listening")
@@ -61,6 +68,12 @@ test("daemon bootstrap activates the exact release through the foreground daemon
 
     assert.equal(activeRelease.releasePath, fixture.root)
     assert.equal(activeRelease.revision, "abc123")
+    assert.deepEqual(status.bootstrap, {
+      attestation: firstAttestation,
+      releaseId: "release-42",
+      releasePath: fixture.root,
+      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")
 
@@ -109,6 +122,7 @@ test("plain daemon startup remains listener-only with no active release", async
 
     assert.equal(status.activeReleaseId, null)
     assert.deepEqual(status.releases, [])
+    assert.equal(status.bootstrap, undefined)
 
     child.kill("SIGTERM")
     assert.equal((await once(child, "exit"))[0], 0)
@@ -118,6 +132,47 @@ test("plain daemon startup remains listener-only with no active release", async
   }
 })
 
+test("ensure-daemon rejects boot attestation instead of inheriting foreground identity", async () => {
+  const fixture = await createFixture()
+
+  try {
+    const result = await runRollbridge(["ensure-daemon", "--config", fixture.configPath, "--boot-attestation", firstAttestation])
+
+    assert.notEqual(result.code, 0)
+    assert.match(result.stderr, /unknown option '--boot-attestation'/)
+    await assert.rejects(() => fs.stat(fixture.socketPath), {code: "ENOENT"})
+    await assert.rejects(() => fs.stat(fixture.startedPath), {code: "ENOENT"})
+  } finally {
+    await fs.rm(fixture.root, {force: true, recursive: true})
+  }
+})
+
+test("otherwise identical foreground boots remain distinguishable by attestation", async () => {
+  const fixture = await createFixture()
+
+  try {
+    const attestations = []
+
+    for (const attestation of [firstAttestation, secondAttestation]) {
+      const child = spawnDaemon(fixture, {attestation, releaseId: "same-release", revision: "same-revision"})
+
+      await waitForLog(child, "control socket listening")
+      const status = await sendControlCommand({command: {command: "status"}, path: fixture.socketPath})
+
+      assert.equal(status.activeReleaseId, "same-release")
+      assert.ok(status.bootstrap && typeof status.bootstrap === "object" && !Array.isArray(status.bootstrap))
+      attestations.push(status.bootstrap.attestation)
+
+      child.kill("SIGTERM")
+      assert.equal((await once(child, "exit"))[0], 0)
+    }
+
+    assert.deepEqual(attestations, [firstAttestation, secondAttestation])
+  } finally {
+    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)
@@ -352,11 +407,15 @@ async function waitForFile(filePath) {
 
 /**
  * @param {{configPath: string, root: string}} fixture - Fixture paths.
- * @param {{releaseId: string, revision: string}} release - Bootstrap metadata.
+ * @param {{attestation?: string, 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"]})
+  const args = [binPath, "daemon", "--config", fixture.configPath, "--release-path", fixture.root, "--release-id", release.releaseId, "--revision", release.revision]
+
+  if (release.attestation) args.push("--boot-attestation", release.attestation)
+
+  return spawn(process.execPath, args, {stdio: ["pipe", "pipe", "pipe"]})
 }
 
 /**
@@ -364,7 +423,15 @@ function spawnDaemon(fixture, release) {
  * @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"]})
+  return await runRollbridge(["daemon", ...args])
+}
+
+/**
+ * @param {string[]} args - Rollbridge command and arguments.
+ * @returns {Promise<{code: number | null, output: string, stderr: string}>} Completed process result.
+ */
+async function runRollbridge(args) {
+  const child = spawn(process.execPath, [binPath, ...args], {stdio: ["ignore", "pipe", "pipe"]})
   let output = ""
   let stderr = ""
 

package/test/rollbridge.test.js

@@ -1161,6 +1161,7 @@ test("deploy can ensure the daemon before sending the release command", async ()
     const proxy = /** @type {{port: number}} */ (status.proxy)
 
     assert.equal(status.activeReleaseId, "ensured-v1")
+    assert.equal(status.bootstrap, undefined)
     assert.match(await fs.readFile(pidPath, "utf8"), /\d+/)
     assert.equal(await fetchTextFromPort(proxy.port, "/release"), "ensured-v1")
   } finally {

package/test/shutdown-completion.test.js

@@ -0,0 +1,290 @@
+// @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 net from "node:net"
+import os from "node:os"
+import path from "node:path"
+import test from "node:test"
+import {fileURLToPath} from "node:url"
+import {normalizeConfig} from "../src/config.js"
+import {sendControlCommand} from "../src/control-client.js"
+import RollbridgeDaemon from "../src/daemon.js"
+import {isProcessAlive} from "../src/state-store.js"
+
+const dummyAppPath = path.join(path.dirname(fileURLToPath(import.meta.url)), "fixtures", "dummy-app.js")
+
+test("shutdown response waits for endpoint and owned-process cleanup before immediate replacement", async () => {
+  const root = await fs.mkdtemp(path.join(os.tmpdir(), "rollbridge-shutdown-completion-"))
+  const socketPath = path.join(root, "control.sock")
+  const unrelatedSocketPath = path.join(root, "unrelated.sock")
+  const gatePath = path.join(root, "shutdown.fifo")
+  const stoppingPath = path.join(root, "stopping")
+  const gate = spawn("mkfifo", [gatePath])
+
+  assert.equal((await once(gate, "exit"))[0], 0)
+
+  const config = buildConfig(socketPath, {
+    companion: {
+      command: `${JSON.stringify(process.execPath)} -e ${JSON.stringify("setInterval(() => {}, 1000)")}`,
+      id: "worker",
+      lifecycle: {drainTimeoutMs: 0, quietCommand: `printf stopping > ${JSON.stringify(stoppingPath)}; read released < ${JSON.stringify(gatePath)}`},
+      policy: "companion"
+    }
+  })
+  const unrelatedConfig = buildConfig(unrelatedSocketPath)
+  const daemon = new RollbridgeDaemon({config, logger: () => {}})
+  const unrelated = new RollbridgeDaemon({config: unrelatedConfig, logger: () => {}})
+  let idleTarget = /** @type {net.Socket | undefined} */ (undefined)
+  let idleUnrelated = /** @type {net.Socket | undefined} */ (undefined)
+  let replacement
+  let gateReleased = false
+
+  try {
+    await daemon.start()
+    await unrelated.start()
+    idleTarget = net.createConnection(socketPath)
+    idleUnrelated = net.createConnection(unrelatedSocketPath)
+    await Promise.all([once(idleTarget, "connect"), once(idleUnrelated, "connect")])
+    await daemon.deploy({releaseId: "v1", releasePath: root, revision: "v1"})
+
+    const workerPid = daemon.activeRelease?.getProcess("worker")?.pid
+
+    assert.equal(typeof workerPid, "number")
+
+    const stopping = waitForFile(stoppingPath)
+    let shutdownResolved = false
+    const shutdown = sendControlCommand({command: {command: "shutdown"}, path: socketPath})
+      .then((response) => {
+        shutdownResolved = true
+        return response
+      })
+
+    await stopping
+
+    let oldEndpointAccepted = true
+
+    try {
+      await sendControlCommand({command: {command: "status"}, path: socketPath})
+    } catch {
+      oldEndpointAccepted = false
+    }
+
+    const resolvedDuringStop = shutdownResolved
+    const processAliveDuringStop = isProcessAlive(/** @type {number} */ (workerPid))
+    const idleTargetClosedDuringStop = idleTarget.destroyed
+    const idleUnrelatedClosedDuringStop = idleUnrelated.destroyed
+
+    // Ensure the RED path cannot leave an idle client handle blocking test cleanup.
+    idleTarget.destroy()
+
+    await fs.writeFile(gatePath, "continue\n")
+    gateReleased = true
+
+    const response = await shutdown
+
+    assert.equal(shutdownResolved, true)
+    assert.equal(resolvedDuringStop, false, "shutdown must not acknowledge while an owned process is still stopping")
+    assert.equal(oldEndpointAccepted, false, "the targeted endpoint must stop accepting new commands before cleanup")
+    assert.equal(processAliveDuringStop, true, "the fixture must hold shutdown while its owned process is alive")
+    assert.equal(idleTargetClosedDuringStop, true, "an idle accepted client must be closed when the targeted endpoint retires")
+    assert.equal(idleUnrelatedClosedDuringStop, false, "an unrelated daemon's accepted clients must remain untouched")
+    assert.deepEqual(response, {message: "shutdown", status: "success"})
+    await assert.rejects(() => fs.stat(socketPath), {code: "ENOENT"})
+    assert.equal(isProcessAlive(/** @type {number} */ (workerPid)), false)
+
+    // A different daemon remains reachable; shutdown is scoped to the targeted control endpoint.
+    assert.equal((await sendControlCommand({command: {command: "status"}, path: unrelatedSocketPath})).application, "shutdown-unrelated")
+
+    // Replacement starts immediately, with no polling or retry between truthful ACK and bind.
+    replacement = new RollbridgeDaemon({config, logger: () => {}})
+    await replacement.start()
+    assert.equal((await sendControlCommand({command: {command: "status"}, path: socketPath})).application, "shutdown-target")
+  } finally {
+    if (!gateReleased) {
+      await fs.writeFile(gatePath, "continue\n").catch(() => {})
+    }
+    idleTarget?.destroy()
+    idleUnrelated?.destroy()
+    if (replacement) await replacement.shutdown()
+    await daemon.shutdown()
+    await unrelated.shutdown()
+    await fs.rm(root, {force: true, recursive: true})
+  }
+})
+
+test("control socket unlink failure is reported only after owned cleanup completes", async () => {
+  const root = await fs.mkdtemp(path.join(os.tmpdir(), "rollbridge-shutdown-unlink-failure-"))
+  const socketPath = path.join(root, "control.sock")
+  const statePath = path.join(root, "state.json")
+  const config = normalizeConfig({...rawConfig(socketPath), statePath})
+  const daemon = new RollbridgeDaemon({config, logger: () => {}})
+
+  try {
+    await daemon.start()
+    await daemon.deploy({releaseId: "v1", releasePath: root, revision: "v1"})
+    if (daemon.pendingWrite) await daemon.pendingWrite
+
+    const webPid = daemon.activeRelease?.getProcess("web")?.pid
+    const proxyPort = daemon.getProxyPort()
+
+    assert.equal(typeof webPid, "number")
+    assert.equal(typeof proxyPort, "number")
+
+    daemon.removeControlSocket = async () => { throw new Error("injected unlink failure") }
+
+    await assert.rejects(
+      () => sendControlCommand({command: {command: "shutdown"}, path: socketPath}),
+      /control socket unlink failed: injected unlink failure/
+    )
+
+    assert.equal(isProcessAlive(/** @type {number} */ (webPid)), false, "unlink failure must not strand an owned process")
+    await assert.rejects(() => fetch(`http://127.0.0.1:${proxyPort}/ping`))
+    await assert.rejects(() => fs.stat(statePath), {code: "ENOENT"})
+  } finally {
+    await fs.rm(root, {force: true, recursive: true})
+  }
+})
+
+test("direct shutdown closes idle accepted clients and converges", async () => {
+  const root = await fs.mkdtemp(path.join(os.tmpdir(), "rollbridge-direct-shutdown-idle-"))
+  const socketPath = path.join(root, "control.sock")
+  const daemon = new RollbridgeDaemon({config: buildConfig(socketPath), logger: () => {}})
+  let idle = /** @type {net.Socket | undefined} */ (undefined)
+
+  try {
+    await daemon.start()
+    idle = net.createConnection(socketPath)
+    await once(idle, "connect")
+    const idleClosed = once(idle, "close")
+
+    await daemon.shutdown()
+    await idleClosed
+
+    assert.equal(idle.destroyed, true)
+    await assert.rejects(() => fs.stat(socketPath), {code: "ENOENT"})
+  } finally {
+    idle?.destroy()
+    await fs.rm(root, {force: true, recursive: true})
+  }
+})
+
+test("shutdown reports cleanup failure and still retires the targeted endpoint", async () => {
+  const root = await fs.mkdtemp(path.join(os.tmpdir(), "rollbridge-shutdown-failure-"))
+  const socketPath = path.join(root, "control.sock")
+  const statePath = path.join(root, "state-directory")
+
+  await fs.mkdir(statePath)
+
+  const config = normalizeConfig({
+    ...rawConfig(socketPath),
+    statePath
+  })
+  const daemon = new RollbridgeDaemon({config, logger: () => {}})
+
+  try {
+    await daemon.start()
+
+    await assert.rejects(
+      () => sendControlCommand({command: {command: "shutdown"}, path: socketPath}),
+      /directory|EISDIR/i
+    )
+    await assert.rejects(() => fs.stat(socketPath), {code: "ENOENT"})
+  } finally {
+    await fs.rm(root, {force: true, recursive: true})
+  }
+})
+
+test("shutdown does not turn an owned-resource stop rejection into success", async () => {
+  const root = await fs.mkdtemp(path.join(os.tmpdir(), "rollbridge-shutdown-stop-failure-"))
+  const socketPath = path.join(root, "control.sock")
+  const config = buildConfig(socketPath)
+  const daemon = new RollbridgeDaemon({config, logger: () => {}})
+  let restoreStop
+
+  try {
+    await daemon.start()
+    await daemon.deploy({releaseId: "v1", releasePath: root, revision: "v1"})
+
+    const release = daemon.activeRelease
+
+    assert.ok(release)
+    const originalStop = release.stop.bind(release)
+
+    restoreStop = originalStop
+    release.stop = async () => { throw new Error("owned release stop failed") }
+
+    await assert.rejects(
+      () => sendControlCommand({command: {command: "shutdown"}, path: socketPath}),
+      /Shutdown failed to stop 1 owned resource/
+    )
+  } finally {
+    if (restoreStop) await restoreStop()
+    await fs.rm(root, {force: true, recursive: true})
+  }
+})
+
+test("shutdown of an already-stopped endpoint fails explicitly", async () => {
+  const root = await fs.mkdtemp(path.join(os.tmpdir(), "rollbridge-shutdown-missing-"))
+  const socketPath = path.join(root, "missing.sock")
+
+  try {
+    await assert.rejects(
+      () => sendControlCommand({command: {command: "shutdown"}, path: socketPath}),
+      (error) => Boolean(error && typeof error === "object" && "code" in error && error.code === "ENOENT")
+    )
+  } finally {
+    await fs.rm(root, {force: true, recursive: true})
+  }
+})
+
+/**
+ * @param {string} socketPath - Control socket path.
+ * @param {{companion?: Record<string, import("../src/json.js").JsonValue>}} [options] - Optional companion process.
+ * @returns {import("../src/config.js").RollbridgeConfig} Normalized config.
+ */
+function buildConfig(socketPath, {companion} = {}) {
+  return normalizeConfig({
+    ...rawConfig(socketPath),
+    ...(companion ? {processes: [companion, ...rawConfig(socketPath).processes]} : {})
+  })
+}
+
+/**
+ * @param {string} socketPath - Control socket path.
+ * @returns {{application: string, control: {path: string}, processes: Record<string, import("../src/json.js").JsonValue>[], proxy: {forceStopTimeoutMs: number, host: string, port: number}}} Raw config.
+ */
+function rawConfig(socketPath) {
+  return {
+    application: socketPath.endsWith("unrelated.sock") ? "shutdown-unrelated" : "shutdown-target",
+    control: {path: socketPath},
+    processes: [{
+      command: `${JSON.stringify(process.execPath)} ${JSON.stringify(dummyAppPath)}`,
+      health: {intervalMs: 25, path: "/ping", timeoutMs: 3000},
+      id: "web",
+      policy: "proxied",
+      port: {from: 0, to: 0}
+    }],
+    proxy: {forceStopTimeoutMs: 1000, host: "127.0.0.1", port: 0}
+  }
+}
+
+/**
+ * @param {string} filePath - File to await without polling.
+ * @returns {Promise<void>} Resolves when the file appears.
+ */
+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
+    }
+  } finally {
+    await watcher.return?.()
+  }
+
+  throw new Error(`Watcher ended before ${filePath} appeared`)
+}