rollbridge 0.1.31 → 0.1.33

package/src/managed-process.js

@@ -4,15 +4,18 @@ import {EventEmitter} from "node:events"
 import {spawn} from "node:child_process"
 import {processGroupHasLiveMembers, processGroupMembers} from "./process-memory.js"
 
+const ACTIVATION_HOOK_TIMEOUT_MS = 30000
+
 /**
  * @typedef {import("./json.js").JsonValue} JsonValue
  * @typedef {"starting" | "running" | "quiesced" | "stopping" | "stopped" | "failed"} ManagedProcessState
  * @typedef {"deploy" | "crash" | "manual" | "memory"} ManagedProcessStartReason
+ * @typedef {"active" | "candidate" | "retired"} LifecycleRole
  * @typedef {import("node:child_process").ChildProcess["signalCode"]} ProcessExitSignal
  * @typedef {{at: string, line: string, stream: "stdout" | "stderr"}} ManagedProcessLog
  * @typedef {import("./config.js").StopTimeoutMs} StopTimeoutMs
  * @typedef {{command: string, cwd: string | undefined, env: Record<string, string | undefined>, lifecycle: import("./config.js").LifecycleConfig, logger: (message: string, data?: Record<string, import("./json.js").JsonValue>) => void, memory: import("./config.js").MemoryConfig | undefined, outputLines: number, restart: import("./config.js").RestartConfig, restartDelayMs: number, shouldRestart: () => boolean, stopSignal: string, stopTimeoutMs: StopTimeoutMs}} ManagedProcessDefinition
- * @typedef {{children: import("./process-memory.js").ProcessGroupMember[], command: string, cwd: string | undefined, exitCode: number | null | undefined, exitSignal: ProcessExitSignal | undefined, id: string, lastMemoryRestartAt: string | undefined, lastStartReason: ManagedProcessStartReason | undefined, logs: ManagedProcessLog[], memoryRestarts: number, pid: number | undefined, restarts: number, rssBytes: number | undefined, startedAt: string | undefined, state: ManagedProcessState, uptimeMs: number | undefined}} ManagedProcessStatus
+ * @typedef {{children: import("./process-memory.js").ProcessGroupMember[], command: string, cwd: string | undefined, exitCode: number | null | undefined, exitSignal: ProcessExitSignal | undefined, id: string, lastMemoryRestartAt: string | undefined, lastStartReason: ManagedProcessStartReason | undefined, lifecycleRole?: LifecycleRole, logs: ManagedProcessLog[], memoryRestarts: number, pid: number | undefined, restarts: number, rssBytes: number | undefined, startedAt: string | undefined, state: ManagedProcessState, uptimeMs: number | undefined}} ManagedProcessStatus
  */
 
 export default class ManagedProcess extends EventEmitter {
@@ -62,6 +65,7 @@ export default class ManagedProcess extends EventEmitter {
     this.memoryWarned = false
     this.startedAtMs = /** @type {number | undefined} */ (undefined)
     this.intentionalStop = false
+    this.lifecycleRole = /** @type {LifecycleRole} */ ("candidate")
     this.intentionalStopSignal = /** @type {ProcessExitSignal | undefined} */ (undefined)
     this.quiescePromise = /** @type {Promise<void> | undefined} */ (undefined)
     this.quiesceError = /** @type {Error | undefined} */ (undefined)
@@ -76,9 +80,11 @@ export default class ManagedProcess extends EventEmitter {
 
   /**
    * @param {ManagedProcessStartReason} [reason] - Why the process is being started (deploy by default; "crash" on auto-restart, "manual" via the restart command).
-   * @returns {Promise<void>} Resolves after spawn.
+   * @param {LifecycleRole} [lifecycleRole] - Exact desired role to restore before reporting the process running.
+   * @returns {Promise<void>} Resolves after spawn and lifecycle-role restoration.
    */
-  async start(reason = "deploy") {
+  async start(reason = "deploy", lifecycleRole) {
+    if (lifecycleRole) this.lifecycleRole = lifecycleRole
     if (this.child) return
 
     this.intentionalStop = false
@@ -109,16 +115,35 @@ export default class ManagedProcess extends EventEmitter {
       })
 
       child.once("spawn", () => {
-        this.state = "running"
-        this.startedAtMs = Date.now()
-        this.lastStartReason = reason
-        this.logger("process started", {command: this.command, id: this.id, pid: child.pid || null, reason})
-        this.startMemoryMonitor()
-        this.emit("started")
-        resolve(undefined)
+        void (async () => {
+          this.startedAtMs = Date.now()
+          this.lastStartReason = reason
+          try {
+            await this.restoreLifecycleRole()
+          } catch (error) {
+            this.state = "failed"
+            this.logger("process lifecycle role restoration failed", {error: error instanceof Error ? error.message : String(error), id: this.id, role: this.lifecycleRole})
+            reject(error)
+            return
+          }
+          if (this.child !== child) {
+            reject(new Error(`Process ${this.id} exited before lifecycle role ${this.lifecycleRole} was restored`))
+            return
+          }
+          this.state = "running"
+          this.logger("process started", {command: this.command, id: this.id, pid: child.pid || null, reason})
+          this.startMemoryMonitor()
+          this.emit("started")
+          resolve(undefined)
+        })()
       })
       child.once("error", (error) => {
         this.state = "failed"
+        if (this.child === child) {
+          this.child = undefined
+          this.pid = undefined
+          this.exitPromise = undefined
+        }
         reject(error)
       })
       child.stdout.setEncoding("utf8")
@@ -157,11 +182,14 @@ export default class ManagedProcess extends EventEmitter {
     for (const line of String(chunk).split(/\r?\n/)) {
       if (!line) continue
 
-      this.logs.push({at: new Date().toISOString(), line, stream})
+      const entry = {at: new Date().toISOString(), line, stream}
+
+      this.logs.push(entry)
 
       if (this.logs.length > this.outputLines) {
         this.logs.splice(0, this.logs.length - this.outputLines)
       }
+      this.emit("log", entry)
     }
   }
 
@@ -321,6 +349,7 @@ export default class ManagedProcess extends EventEmitter {
     if (this.memoryRestarting) return
 
     this.memoryRestarting = true
+    const lifecycleRole = this.lifecycleRole
 
     try {
       await this.stop()
@@ -333,7 +362,7 @@ export default class ManagedProcess extends EventEmitter {
       this.memoryRestarts += 1
       this.lastMemoryRestartAtMs = Date.now()
       this.memoryWarned = false
-      await this.start("memory")
+      await this.start("memory", lifecycleRole)
     } catch (error) {
       this.logger("memory restart failed", {error: error instanceof Error ? error.message : String(error), id: this.id})
     } finally {
@@ -415,11 +444,15 @@ export default class ManagedProcess extends EventEmitter {
       }
       if (!this.child?.pid) {
         this.state = "stopped"
+        if (this.lifecycle.activateCommand) this.lifecycleRole = "retired"
         return
       }
       this.state = "stopping"
       if (this.lifecycle.quietCommand) this.quiesceError = await this.runHook(this.lifecycle.quietCommand, this.hookTimeoutMs(), "quiet command")
-      if (!this.quiesceError) this.state = "quiesced"
+      if (!this.quiesceError) {
+        this.state = "quiesced"
+        if (this.lifecycle.activateCommand) this.lifecycleRole = "retired"
+      }
     })()
     return await this.quiescePromise
   }
@@ -430,6 +463,44 @@ export default class ManagedProcess extends EventEmitter {
     if (this.quiesceError) throw this.quiesceError
   }
 
+  /** Re-runs the idempotent quiet hook for an explicitly resumed durable transition. */
+  async requiesceStrict() {
+    this.quiescePromise = undefined
+    this.quiesceError = undefined
+    await this.quiesceStrict()
+  }
+
+  /** Runs the opt-in generation activation command and rejects on any hook failure. */
+  async activateStrict() {
+    const command = this.lifecycle.activateCommand
+
+    if (!command) return
+    const error = await this.runHook(command, ACTIVATION_HOOK_TIMEOUT_MS, "activate command", this.pid)
+
+    if (error) throw error
+    this.lifecycleRole = "active"
+  }
+
+  /**
+   * Records the durable desired role without firing a lifecycle command.
+   * @param {LifecycleRole} role - Exact role owned by this process generation.
+   */
+  async setLifecycleRole(role) {
+    this.lifecycleRole = role
+  }
+
+  /** Restores an active or retired role after this exact process starts. */
+  async restoreLifecycleRole() {
+    if (!this.lifecycle.activateCommand || this.lifecycleRole === "candidate") return
+    const command = this.lifecycleRole === "active" ? this.lifecycle.activateCommand : this.lifecycle.quietCommand
+
+    if (!command) throw new Error(`Process ${this.id} cannot restore lifecycle role ${this.lifecycleRole} without its paired command`)
+    const timeoutMs = this.lifecycleRole === "active" ? ACTIVATION_HOOK_TIMEOUT_MS : this.hookTimeoutMs()
+    const error = await this.runHook(command, timeoutMs, `${this.lifecycleRole === "active" ? "activate" : "quiet"} command`, this.pid)
+
+    if (error) throw error
+  }
+
   /** @returns {number} Timeout used for lifecycle hooks. */
   hookTimeoutMs() {
     if (this.stopTimeoutMs === "indefinite") return 30000
@@ -642,6 +713,7 @@ export default class ManagedProcess extends EventEmitter {
       id: this.id,
       lastMemoryRestartAt: this.lastMemoryRestartAtMs === undefined ? undefined : new Date(this.lastMemoryRestartAtMs).toISOString(),
       lastStartReason: this.lastStartReason,
+      ...(this.lifecycle.activateCommand ? {lifecycleRole: this.lifecycleRole} : {}),
       logs: this.logs.slice(-this.outputLines),
       memoryRestarts: this.memoryRestarts,
       pid: this.pid,

package/src/process-guardian.js

@@ -24,6 +24,7 @@ import ManagedProcess from "./managed-process.js"
  * @property {import("./json.js").JsonValue} [authority] - Expected current authority.
  * @property {import("./json.js").JsonValue} [nextAuthority] - Requested replacement authority.
  * @property {import("./managed-process.js").ManagedProcessStartReason} [reason] - Start reason.
+ * @property {import("./managed-process.js").LifecycleRole} [lifecycleRole] - Desired generation role restored during start.
  * @property {string} token - Authentication token.
  */
 
@@ -299,6 +300,7 @@ async function execute(request, socket) {
 
   if (request.command === "commit-retired-owner-replacement") {
     requireReplacement(socket, request)
+    requireProcess(request)
     if (!replacementOwnerState) throw new Error("Retired owner replacement transaction is not staged")
     if (!isDeepStrictEqual(ownerAuthority(ownerState), replacementAuthority)) throw new Error("Retired owner replacement requires unchanged owner authority")
     const controlPath = ownerControlPath(ownerState)
@@ -396,6 +398,9 @@ async function execute(request, socket) {
       ? legacyGuardian.process(request.key, managedDefinition)
       : new ManagedProcess(managedDefinition)
 
+    managedProcess.on("log", (entry) => {
+      broadcast({entry, event: "process-log", key: request.key, status: managedProcess.status()})
+    })
     if (recoversLegacyProcess && "recover" in managedProcess && typeof managedProcess.recover === "function") await managedProcess.recover()
 
     record.process = managedProcess
@@ -404,19 +409,24 @@ async function execute(request, socket) {
     return managedProcess.status()
   }
 
-  if (!request.key) throw new Error(`Guardian ${request.command} requires a process key`)
-  const record = processes.get(request.key)
-
-  if (!record) throw new Error(`Guardian process ${request.key} is not registered`)
+  const record = requireProcess(request)
 
   if (request.command !== "status") requireOwner(socket, request.command)
 
   if (request.command === "start") {
     record.desired = true
-    await record.process.start(request.reason)
+    await record.process.start(request.reason, request.lifecycleRole)
+  } else if (request.command === "activate") {
+    await record.process.activateStrict()
   } else if (request.command === "quiesce") {
     record.desired = false
     await record.process.quiesceStrict()
+  } else if (request.command === "requiesce") {
+    record.desired = false
+    await record.process.requiesceStrict()
+  } else if (request.command === "set-lifecycle-role") {
+    if (request.lifecycleRole !== "active" && request.lifecycleRole !== "candidate" && request.lifecycleRole !== "retired") throw new Error("Guardian lifecycle role is invalid")
+    await record.process.setLifecycleRole(request.lifecycleRole)
   } else if (request.command === "stop") {
     record.desired = false
     await record.process.stop(request.options)
@@ -518,6 +528,18 @@ function requireReplacement(socket, request) {
   if (replacementClient !== socket || request.replacementId !== replacementId) throw new Error("Owner replacement transaction is not the prepared candidate")
 }
 
+/**
+ * @param {GuardianRequest} request - Keyed guardian request.
+ * @returns {{desired: boolean, process: ManagedProcess, provenance: string}} Exact registered process.
+ */
+function requireProcess(request) {
+  if (!request.key) throw new Error(`Guardian ${request.command} requires a process key`)
+  const record = processes.get(request.key)
+
+  if (!record) throw new Error(`Guardian process ${request.key} is not registered`)
+  return record
+}
+
 /**
  * @param {import("./json.js").JsonValue} state - Transfer state.
  * @returns {import("./json.js").JsonValue} Embedded authority fence.

package/src/release-group.js

@@ -116,8 +116,9 @@ export default class ReleaseGroup extends EventEmitter {
   /**
    * Reconstructs this release around processes still owned by the durable guardian.
    * @param {ReleaseStatus} snapshot - Persisted release snapshot.
+   * @param {{synchronizeLifecycleRole?: boolean}} [options] - Guardian role synchronization options.
    */
-  async restore(snapshot) {
+  async restore(snapshot, {synchronizeLifecycleRole = true} = {}) {
     if (!snapshot || snapshot.releaseId !== this.releaseId || snapshot.releasePath !== this.releasePath || snapshot.revision !== this.revision) {
       throw new Error(`Persisted release identity mismatch for ${this.releaseId}`)
     }
@@ -175,6 +176,17 @@ export default class ReleaseGroup extends EventEmitter {
       if (processConfig.nonBlockingDrain) this.nonBlockingDrainIds.add(processStatus.id)
       if ("recover" in processInstance && typeof processInstance.recover === "function") await processInstance.recover()
     }
+    if (synchronizeLifecycleRole) await this.synchronizeLifecycleRoles()
+  }
+
+  /** Synchronizes only the activation owner's durable role without firing its hook. */
+  async synchronizeLifecycleRoles() {
+    const processConfig = this.config.processes.find((candidate) => candidate.lifecycle.activateCommand !== undefined)
+
+    if (!processConfig) return
+    const lifecycleRole = this.state === "active" ? "active" : this.state === "draining" ? "retired" : "candidate"
+
+    await Promise.all(this.getProcesses(processConfig.id).map(({process}) => process.setLifecycleRole(lifecycleRole)))
   }
 
   /**
@@ -253,6 +265,17 @@ export default class ReleaseGroup extends EventEmitter {
     this.activatedAt = new Date().toISOString()
   }
 
+  /** Runs the configured release-generation activation acknowledgement, if any. */
+  async activateGeneration() {
+    const processConfig = this.config.processes.find((candidate) => candidate.lifecycle.activateCommand !== undefined)
+
+    if (!processConfig) return
+    const [instance] = this.getProcesses(processConfig.id)
+
+    if (!instance) throw new Error(`Generation activation process ${processConfig.id} is not running for release ${this.releaseId}`)
+    await instance.process.activateStrict()
+  }
+
   /** @returns {Promise<void>} Allocates all configured per-process ports. */
   async allocatePorts() {
     if (this.portsAllocated) return
@@ -295,12 +318,12 @@ export default class ReleaseGroup extends EventEmitter {
   }
 
   /**
-   * Builds a managed process from config.
+   * Builds one rendered managed-process definition without registering ownership.
    * @param {import("./config.js").ProcessConfig} processConfig - Process config.
    * @param {BuildProcessOptions} [options] - Build options.
-   * @returns {ManagedProcess} Managed process.
+   * @returns {ConstructorParameters<typeof ManagedProcess>[0] & import("./managed-process.js").ManagedProcessDefinition} Managed process definition.
    */
-  buildProcess(processConfig, options = {}) {
+  processDefinition(processConfig, options = {}) {
     const index = options.index ?? 0
     const count = options.count ?? 1
     const instanceId = options.instanceId ?? processConfig.id
@@ -311,12 +334,12 @@ export default class ReleaseGroup extends EventEmitter {
       ...renderedEnv
     }
 
-    const definition = /** @type {ConstructorParameters<typeof ManagedProcess>[0]} */ ({
+    return {
       command: renderTemplate(processConfig.command, context),
       cwd: processConfig.cwd ? renderTemplate(processConfig.cwd, context) : this.releasePath,
       env: processEnv,
       id: instanceId,
-      lifecycle: processConfig.lifecycle,
+      lifecycle: processConfig.lifecycle || {drainTimeoutMs: 0},
       logger: (message, data = {}) => this.logger(message, {processId: instanceId, releaseId: this.releaseId, ...data}),
       memory: processConfig.memory,
       outputLines: processConfig.outputLines,
@@ -325,7 +348,18 @@ export default class ReleaseGroup extends EventEmitter {
       shouldRestart: options.shouldRestart || (() => this.state === "active" || this.state === "starting"),
       stopSignal: processConfig.stopSignal,
       stopTimeoutMs: processConfig.gracefulStopMs
-    })
+    }
+  }
+
+  /**
+   * Builds a managed process from config.
+   * @param {import("./config.js").ProcessConfig} processConfig - Process config.
+   * @param {BuildProcessOptions} [options] - Build options.
+   * @returns {ManagedProcess} Managed process.
+   */
+  buildProcess(processConfig, options = {}) {
+    const definition = this.processDefinition(processConfig, options)
+    const instanceId = options.instanceId ?? processConfig.id
 
     return this.processFactory
       ? this.processFactory(options.guardianKey || `release:${this.releaseId}:${instanceId}`, definition)
@@ -347,7 +381,7 @@ export default class ReleaseGroup extends EventEmitter {
 
       for (let index = 0; index < instances.length; index += 1) {
         const instance = instances[index]
-        const nextDefinition = this.buildProcess(processConfig, {
+        const nextDefinition = this.processDefinition(processConfig, {
           count: processConfig.replicas,
           index,
           instanceId: instance.id
@@ -543,21 +577,25 @@ export default class ReleaseGroup extends EventEmitter {
   /**
    * Marks the generation retired and quiesces its jobs-main and non-blocking workers as one unit.
    * @param {import("./config.js").RollbridgeConfig} [config] - Refreshed retirement config.
+   * @param {{retry?: boolean}} [options] - Explicit durable-transition resume options.
    * @returns {Promise<void>} Resolves when retirement quiescence succeeds.
    */
-  async beginRetirement(config = this.config) {
+  async beginRetirement(config = this.config, {retry = false} = {}) {
     if (this.state === "draining") {
-      if (this.retirementError) throw new Error(this.retirementError)
-      return
+      if (!retry) {
+        if (this.retirementError) throw new Error(this.retirementError)
+        return
+      }
+    } else {
+      this.state = "draining"
+      this.drainStartedAt = new Date().toISOString()
     }
 
-    this.state = "draining"
-    this.drainStartedAt = new Date().toISOString()
     this.refreshProcessDefinitions(config)
     const generationIds = new Set([...this.handoffServiceIds, ...this.nonBlockingDrainIds])
     const results = await Promise.allSettled([...this.processes.entries()]
       .filter(([id]) => generationIds.has(id))
-      .map(([, processInstance]) => processInstance.quiesceStrict()))
+      .map(([, processInstance]) => retry ? processInstance.requiesceStrict() : processInstance.quiesceStrict()))
     const errors = results.filter((result) => result.status === "rejected").map((result) => result.reason)
 
     if (errors.length > 0) {
@@ -565,6 +603,7 @@ export default class ReleaseGroup extends EventEmitter {
       this.retirementError = `${failure.message}: ${errors.map((error) => error instanceof Error ? error.message : String(error)).join("; ")}`
       throw failure
     }
+    this.retirementError = undefined
   }
 
   /** @returns {Promise<void>} Stops all release-owned processes. */

package/test/config-validation.test.js

@@ -204,6 +204,50 @@ test("validateConfig defaults lifecycle, accepts hooks, and rejects bad values",
   assert.deepEqual(validateLifecycle({stopCommand: "kill -TERM $ROLLBRIDGE_PID"}).issues, [])
 })
 
+test("validateConfig accepts one durable handoff activation lifecycle and rejects unsafe placements", () => {
+  const base = {
+    application: "demo",
+    control: {path: "/tmp/demo.sock"},
+    ownerRecovery: {reconnectGraceMs: 30000},
+    processes: [
+      {command: "run web", id: "web", policy: "proxied", port: {from: 18000, to: 18099}},
+      {
+        command: "run jobs",
+        deployStrategy: "handoff",
+        id: "jobs",
+        lifecycle: {activateCommand: "jobs activate", quietCommand: "jobs retire"},
+        policy: "service",
+        port: {from: 18100, to: 18199}
+      }
+    ],
+    proxy: {host: "127.0.0.1", port: 8182},
+    statePath: "/tmp/demo.state.json"
+  }
+  const valid = validateConfig(base)
+
+  assert.deepEqual(valid.issues, [])
+  assert.equal(valid.config.processes[1].lifecycle.activateCommand, "jobs activate")
+
+  const invalidType = validateConfig({...base, processes: [base.processes[0], {...base.processes[1], lifecycle: {activateCommand: 5, quietCommand: "jobs retire"}}]})
+  assert.ok(invalidType.issues.some((issue) => issue.message === "processes[1].lifecycle.activateCommand must be a string"))
+
+  const missingRetirement = validateConfig({...base, processes: [base.processes[0], {...base.processes[1], lifecycle: {activateCommand: "jobs activate"}}]})
+  assert.ok(missingRetirement.issues.some((issue) => /requires lifecycle\.quietCommand/.test(issue.message)))
+
+  const nonHandoff = validateConfig({...base, processes: [base.processes[0], {...base.processes[1], deployStrategy: "persistent"}]})
+  assert.ok(nonHandoff.issues.some((issue) => /activateCommand.*handoff service/.test(issue.message)))
+
+  const withoutRecovery = validateConfig({...base, ownerRecovery: undefined, statePath: undefined})
+  assert.ok(withoutRecovery.issues.some((issue) => /activateCommand requires ownerRecovery and statePath/.test(issue.message)))
+
+  const duplicate = validateConfig({...base, processes: [
+    base.processes[0],
+    base.processes[1],
+    {...base.processes[1], id: "jobs-secondary", port: {from: 18200, to: 18299}}
+  ]})
+  assert.ok(duplicate.issues.some((issue) => /at most one lifecycle\.activateCommand/.test(issue.message)))
+})
+
 test("validateConfig accepts indefinite graceful stop windows", () => {
   const {config, issues} = validateConfig({
     application: "demo",

package/test/guardian-client.test.js

@@ -2,6 +2,7 @@
 
 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"
@@ -49,6 +50,44 @@ test("guardian inventory removes only an exact owned provenance", async () => {
   }
 })
 
+test("guardian runs a strict activation lifecycle command for the exact registered process", async () => {
+  const fixture = await createGuardian()
+  const activationPath = path.join(fixture.root, "activated")
+  const processInstance = fixture.client.process("candidate-activation", {
+    ...definition("candidate-activation"),
+    lifecycle: {activateCommand: `printf activated > ${JSON.stringify(activationPath)}`, drainTimeoutMs: 0}
+  })
+
+  try {
+    await processInstance.start()
+    await processInstance.activateStrict()
+    assert.equal(await fs.readFile(activationPath, "utf8"), "activated")
+  } finally {
+    await cleanupGuardian(fixture)
+  }
+})
+
+test("guardian forwards each retained output line to its exact process proxy", async () => {
+  const fixture = await createGuardian()
+  const marker = "guardian-output-ready"
+  const processInstance = fixture.client.process("output", {
+    ...definition("output"),
+    command: `${JSON.stringify(process.execPath)} -e ${JSON.stringify(`console.log(${JSON.stringify(marker)})`)}`
+  })
+  const logged = once(processInstance, "log")
+  const exitedFirst = once(processInstance, "exit").then(() => { throw new Error("Guardian process exited before forwarding retained output") })
+
+  try {
+    await processInstance.start()
+    const [entry] = await Promise.race([logged, exitedFirst])
+
+    assert.equal(entry.line, marker)
+    assert.ok(processInstance.status().logs.some((candidate) => candidate.line === marker))
+  } finally {
+    await cleanupGuardian(fixture)
+  }
+})
+
 test("guardian shutdown reports an exact owned process stop failure", async () => {
   const fixture = await createGuardian()
   const processInstance = fixture.client.process("broken-stop", {...definition("broken-stop"), stopSignal: "NOT_A_SIGNAL"})
@@ -171,32 +210,68 @@ test("replacement staging rejects owner state published after prepare", async ()
   }
 })
 
+test("retired owner replacement commit carries its exact recovered process key", async () => {
+  const client = new GuardianClient({socketPath: "/unused", token: "authenticated-capability"})
+  const replacementId = "prepared-replacement"
+  const processKey = "release:v1:worker"
+
+  client.request = async (request) => {
+    if (!request.key) throw new Error(`Guardian ${request.command} requires a process key`)
+    assert.deepEqual(request, {command: "commit-retired-owner-replacement", key: processKey, replacementId})
+    return {committed: true}
+  }
+
+  await client.commitRetiredOwnerReplacement(replacementId, processKey)
+})
+
 test("retired owner replacement requires unchanged authority and the exact control path absent", async () => {
   const fixture = await createGuardian()
   const candidate = new GuardianClient({socketPath: fixture.client.socketPath, token: fixture.token})
+  const contender = new GuardianClient({socketPath: fixture.client.socketPath, token: fixture.token})
   const controlPath = path.join(fixture.root, "rollbridge.sock")
+  const processKey = "release:v1:worker"
   const authority = {configDigest: "incumbent", runtime: null}
   const nextAuthority = {configDigest: "candidate", runtime: null}
   const snapshot = {activeReleaseId: "v1", control: {path: controlPath}}
 
   try {
+    await fixture.client.process(processKey, definition("worker")).recover()
     await fixture.client.publishOwnerState({authority, snapshot})
     await candidate.connect()
     const changed = await candidate.prepareOwnerReplacement(authority, nextAuthority)
 
     await candidate.stageOwnerReplacement(changed.replacementId, {authority: nextAuthority, snapshot})
-    await assert.rejects(() => candidate.commitRetiredOwnerReplacement(changed.replacementId), /unchanged owner authority/)
+    await assert.rejects(() => candidate.commitRetiredOwnerReplacement(changed.replacementId, processKey), /unchanged owner authority/)
     await candidate.abortOwnerReplacement(changed.replacementId)
 
     const occupied = await candidate.prepareOwnerReplacement(authority, authority)
 
     await candidate.stageOwnerReplacement(occupied.replacementId, {authority, snapshot})
     await fs.writeFile(controlPath, "occupied\n")
-    await assert.rejects(() => candidate.commitRetiredOwnerReplacement(occupied.replacementId), /control socket .* still exists/)
+    await assert.rejects(() => candidate.commitRetiredOwnerReplacement(occupied.replacementId, processKey), /control socket .* still exists/)
     await candidate.abortOwnerReplacement(occupied.replacementId)
-    await fixture.client.shutdown()
+
+    await fs.rm(controlPath)
+    const ready = await candidate.prepareOwnerReplacement(authority, authority)
+
+    await candidate.stageOwnerReplacement(ready.replacementId, {authority, snapshot})
+    await contender.connect()
+    await assert.rejects(
+      () => contender.request({command: "commit-retired-owner-replacement", key: processKey, replacementId: ready.replacementId}),
+      /not the prepared candidate/
+    )
+    await assert.rejects(
+      () => candidate.commitRetiredOwnerReplacement(ready.replacementId, "release:v1:wrong"),
+      /process .* is not registered/
+    )
+    const committed = candidate.waitForEvent("replacement-committed")
+
+    await candidate.commitRetiredOwnerReplacement(ready.replacementId, processKey)
+    await committed
+    await candidate.shutdown()
     await fixture.client.guardianExit()
   } finally {
+    contender.disconnect()
     candidate.disconnect()
     await cleanupGuardian(fixture)
   }

package/test/managed-process.test.js

@@ -66,6 +66,21 @@ test("keeps every output line when fewer than the retention limit are produced",
   assert.deepEqual(logs.map((entry) => entry.line), ["one", "two"])
 })
 
+test("emits each output line after retaining it", () => {
+  const managed = buildProcess(50)
+  let observed
+
+  managed.once("log", (entry) => {
+    observed = {entry, retained: managed.status().logs}
+  })
+  managed.appendLog("stdout", "ready\n")
+
+  assert.deepEqual(observed, {
+    entry: managed.status().logs[0],
+    retained: managed.status().logs
+  })
+})
+
 test("reports zeroed restart and uptime fields before the process starts", () => {
   const status = buildProcess(50).status()
 
@@ -385,6 +400,24 @@ test("a hanging lifecycle hook is bounded so stop still completes", async () =>
   }
 })
 
+test("activateStrict runs the configured activation command once per call and rejects failures", async () => {
+  const commands = /** @type {{command: string, label: string, pid: number | undefined, timeoutMs: number}[]} */ ([])
+  const managed = buildLongLived(() => false)
+
+  managed.lifecycle = {activateCommand: "jobs activate", drainTimeoutMs: 0}
+  managed.pid = 4321
+  managed.runHook = async (command, timeoutMs, label, pid) => {
+    commands.push({command, label, pid, timeoutMs})
+    return undefined
+  }
+
+  await managed.activateStrict()
+  assert.deepEqual(commands, [{command: "jobs activate", label: "activate command", pid: 4321, timeoutMs: 30000}])
+
+  managed.runHook = async () => new Error("activation rejected")
+  await assert.rejects(() => managed.activateStrict(), /activation rejected/)
+})
+
 test("sends the configured stopSignal as the graceful stop signal", async () => {
   const dir = fs.mkdtempSync(path.join(os.tmpdir(), "rollbridge-stop-signal-"))
   const readyPath = path.join(dir, "ready")