rollbridge 0.1.73 → 0.1.75

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (70) hide show
  1. package/README.md +63 -10
  2. package/TODO.md +13 -0
  3. package/changelog.d/20261025-guardian-re-register-dead-generation.md +13 -0
  4. package/changelog.d/20261026-stale-committed-generation-transition-recovery.md +1 -0
  5. package/changelog.d/20261104-compose-service-units.md +21 -0
  6. package/changelog.d/20261105-owner-mutation-lease-diagnostics.md +20 -0
  7. package/changelog.d/20261106-release-dependency-boot-budgets.md +32 -0
  8. package/changelog.d/20261109-path-filtered-builds.md +11 -0
  9. package/changelog.d/20261110-default-boot-budget-above-measured-startup.md +26 -0
  10. package/changelog.d/20261111-contention-sensitive-daemon-specs.md +27 -0
  11. package/changelog.d/20261113-bounded-nonblocking-retirement.md +5 -0
  12. package/changelog.d/20261115-bound-draining-release-groups.md +62 -0
  13. package/changelog.d/20261115-restore-deploy-refuses-held-generation.md +27 -0
  14. package/changelog.d/20261115-wedged-generation-escalation.md +44 -0
  15. package/changelog.d/20261116-bounded-explicit-stop-retirement.md +30 -0
  16. package/changelog.d/20261116-config-json-canonical-shape.md +11 -0
  17. package/changelog.d/20261116-drain-specs-gate-the-retirement-record.md +29 -0
  18. package/changelog.d/20261116-guardian-version-handoff.md +37 -0
  19. package/changelog.d/20261116-reclaim-dead-owner-mutation.md +7 -0
  20. package/changelog.d/20261117-activate-before-incumbent-retirement.md +1 -0
  21. package/changelog.d/20261117-activation-path-drain-deadline.md +35 -0
  22. package/changelog.d/20261117-stop-companion-after-retired-dependency.md +7 -0
  23. package/changelog.d/20261118-bounded-control-client-close.md +4 -0
  24. package/changelog.d/20261118-incumbent-retirement-authority-guard.md +1 -0
  25. package/changelog.d/20261118-owner-retirement-no-guardian-bound.md +19 -0
  26. package/changelog.d/20261118-shutdown-retirement-bound-restored.md +31 -0
  27. package/docs/cli.md +128 -3
  28. package/docs/compose-services.md +222 -0
  29. package/docs/config.md +177 -6
  30. package/docs/troubleshooting.md +97 -6
  31. package/docs/velocious.md +1 -1
  32. package/docs/workers.md +11 -0
  33. package/examples/tensorbuzz.com.js +3 -2
  34. package/package.json +1 -1
  35. package/src/cli.js +69 -3
  36. package/src/compose-unit.js +725 -0
  37. package/src/config.js +346 -8
  38. package/src/control-client.js +32 -5
  39. package/src/daemon.js +448 -76
  40. package/src/doctor.js +74 -0
  41. package/src/drain-policy.js +252 -0
  42. package/src/guardian-client.js +92 -9
  43. package/src/health.js +99 -8
  44. package/src/managed-process.js +197 -16
  45. package/src/process-guardian.js +212 -22
  46. package/src/process-memory.js +62 -2
  47. package/src/process-order.js +26 -0
  48. package/src/release-group.js +452 -39
  49. package/tensorbuzz.yml +20 -1
  50. package/test/completion.test.js +5 -2
  51. package/test/compose-config.test.js +160 -0
  52. package/test/compose-docker.test.js +297 -0
  53. package/test/compose-unit.test.js +415 -0
  54. package/test/config-validation.test.js +135 -5
  55. package/test/control-protocol.test.js +22 -0
  56. package/test/drain-policy.test.js +328 -0
  57. package/test/fixtures/deferred-boot-app.js +106 -0
  58. package/test/fixtures/gated-app.js +50 -0
  59. package/test/guardian-client.test.js +149 -5
  60. package/test/health.test.js +74 -1
  61. package/test/managed-process.test.js +260 -1
  62. package/test/owner-recovery.test.js +151 -20
  63. package/test/owner-replacement.test.js +176 -15
  64. package/test/process-memory.test.js +47 -1
  65. package/test/release-group.test.js +447 -2
  66. package/test/rollbridge.test.js +774 -72
  67. package/test/shutdown-completion.test.js +119 -0
  68. package/test/shutdown-retirement-bound.test.js +162 -0
  69. package/test/support/process.js +3 -1
  70. package/test/tensorbuzz-config.test.js +228 -0
@@ -2,10 +2,17 @@
2
2
 
3
3
  import {EventEmitter} from "node:events"
4
4
  import {spawn} from "node:child_process"
5
- import {processGroupHasLiveMembers, processGroupMembers, processStartTime} from "./process-memory.js"
5
+ import {processGroupHasLiveMembers, processGroupMembers, processStartTime, sampleProcessGroup} from "./process-memory.js"
6
6
 
7
7
  const DEFAULT_ACTIVATION_HOOK_TIMEOUT_MS = 30000
8
8
  const MAX_BUFFERED_OUTPUT_CHARACTERS = 64 * 1024
9
+ // Reading a process group means scanning procfs, and status() is read continuously. A held
10
+ // group is re-verified on this interval instead of on every read.
11
+ const HELD_GROUP_RECHECK_MS = 5000
12
+ // How long an escalated SIGKILL is given to clear the group before the group is recorded as
13
+ // outliving it again. Bounded so the escalation itself can never become the unbounded wait it
14
+ // replaced.
15
+ const ESCALATION_KILL_CONFIRM_MS = 5000
9
16
 
10
17
  /**
11
18
  * @typedef {import("./json.js").JsonValue} JsonValue
@@ -15,8 +22,9 @@ const MAX_BUFFERED_OUTPUT_CHARACTERS = 64 * 1024
15
22
  * @typedef {import("node:child_process").ChildProcess["signalCode"]} ProcessExitSignal
16
23
  * @typedef {{at: string, line: string, stream: "stdout" | "stderr"}} ManagedProcessLog
17
24
  * @typedef {import("./config.js").StopTimeoutMs} StopTimeoutMs
18
- * @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
19
- * @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, processStartTime?: string, restarts: number, rssBytes: number | undefined, startedAt: string | undefined, state: ManagedProcessState, uptimeMs: number | undefined}} ManagedProcessStatus
25
+ * @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, shouldStop?: () => boolean, stopSignal: string, stopTimeoutMs: StopTimeoutMs}} ManagedProcessDefinition
26
+ * @typedef {{liveMemberCount: number | undefined, pgid: number}} HeldProcessGroup
27
+ * @typedef {{children: import("./process-memory.js").ProcessGroupMember[], command: string, cwd: string | undefined, exitCode: number | null | undefined, exitSignal: ProcessExitSignal | undefined, heldProcessGroup: HeldProcessGroup | undefined, id: string, lastMemoryRestartAt: string | undefined, lastStartReason: ManagedProcessStartReason | undefined, lifecycleRole?: LifecycleRole, logs: ManagedProcessLog[], memoryRestarts: number, pid: number | undefined, processStartTime?: string, restarts: number, retirementTimedOut: boolean, rssBytes: number | undefined, startedAt: string | undefined, state: ManagedProcessState, uptimeMs: number | undefined}} ManagedProcessStatus
20
28
  */
21
29
 
22
30
  export default class ManagedProcess extends EventEmitter {
@@ -33,10 +41,11 @@ export default class ManagedProcess extends EventEmitter {
33
41
  * @param {import("./config.js").RestartConfig} [args.restart] - Restart policy (defaults to unlimited restarts with a constant delay).
34
42
  * @param {number} args.restartDelayMs - Restart delay.
35
43
  * @param {() => boolean} args.shouldRestart - Restart policy callback.
44
+ * @param {() => boolean} [args.shouldStop] - Whether an unexpected exit is terminal because its dependency retired.
36
45
  * @param {string} [args.stopSignal] - Signal sent to gracefully stop the process (default "SIGTERM").
37
46
  * @param {StopTimeoutMs} args.stopTimeoutMs - Stop timeout.
38
47
  */
39
- constructor({command, cwd, env, id, lifecycle = {drainTimeoutMs: 0}, logger, memory, outputLines, restart = {backoffFactor: 1, maxDelayMs: 0, maxRestarts: undefined, windowMs: 0}, restartDelayMs, shouldRestart, stopSignal = "SIGTERM", stopTimeoutMs}) {
48
+ constructor({command, cwd, env, id, lifecycle = {drainTimeoutMs: 0}, logger, memory, outputLines, restart = {backoffFactor: 1, maxDelayMs: 0, maxRestarts: undefined, windowMs: 0}, restartDelayMs, shouldRestart, shouldStop = () => false, stopSignal = "SIGTERM", stopTimeoutMs}) {
40
49
  super()
41
50
 
42
51
  this.command = command
@@ -50,6 +59,7 @@ export default class ManagedProcess extends EventEmitter {
50
59
  this.restart = restart
51
60
  this.restartDelayMs = restartDelayMs
52
61
  this.shouldRestart = shouldRestart
62
+ this.shouldStop = shouldStop
53
63
  this.stopSignal = stopSignal
54
64
  this.stopTimeoutMs = stopTimeoutMs
55
65
  this.state = /** @type {ManagedProcessState} */ ("stopped")
@@ -73,6 +83,10 @@ export default class ManagedProcess extends EventEmitter {
73
83
  this.quiescePromise = /** @type {Promise<void> | undefined} */ (undefined)
74
84
  this.quiesceError = /** @type {Error | undefined} */ (undefined)
75
85
  this.stopPromise = /** @type {Promise<void> | undefined} */ (undefined)
86
+ this.retirementTimedOut = false
87
+ this.groupOutlivedStop = /** @type {number | undefined} */ (undefined)
88
+ this.heldProcessGroupCheckedAtMs = /** @type {number | undefined} */ (undefined)
89
+ this.heldProcessGroupCount = /** @type {number | undefined} */ (undefined)
76
90
  this.operationRevision = 0
77
91
  this.restartTimer = undefined
78
92
  this.child = undefined
@@ -101,6 +115,10 @@ export default class ManagedProcess extends EventEmitter {
101
115
  this.quiescePromise = undefined
102
116
  this.quiesceError = undefined
103
117
  this.stopPromise = undefined
118
+ this.retirementTimedOut = false
119
+ this.groupOutlivedStop = undefined
120
+ this.heldProcessGroupCheckedAtMs = undefined
121
+ this.heldProcessGroupCount = undefined
104
122
  this.exitCode = undefined
105
123
  this.exitSignal = undefined
106
124
  this.state = "starting"
@@ -217,6 +235,7 @@ export default class ManagedProcess extends EventEmitter {
217
235
  this.restart = definition.restart
218
236
  this.restartDelayMs = definition.restartDelayMs
219
237
  this.shouldRestart = definition.shouldRestart
238
+ this.shouldStop = definition.shouldStop ?? (() => false)
220
239
  this.stopSignal = definition.stopSignal
221
240
  this.stopTimeoutMs = definition.stopTimeoutMs
222
241
  }
@@ -276,15 +295,80 @@ export default class ManagedProcess extends EventEmitter {
276
295
  this.rssBytes = undefined
277
296
  this.children = []
278
297
  this.clearMemoryMonitor()
279
- this.state = wasIntentional ? "stopped" : "failed"
298
+ const terminalExit = !wasIntentional && this.shouldStop()
299
+ this.state = wasIntentional || terminalExit ? "stopped" : "failed"
300
+
280
301
  this.logger("process exited", {code, id: this.id, signal})
281
302
  this.emit("exit", {code, signal})
282
303
 
283
- if (!wasIntentional && this.shouldRestart()) {
304
+ if (!wasIntentional && !terminalExit && this.shouldRestart()) {
284
305
  this.scheduleRestart()
285
306
  }
286
307
  }
287
308
 
309
+ /**
310
+ * Records that the owned process group was still alive when the bounded stop gave up.
311
+ *
312
+ * Every process is spawned `detached: true`, so the tracked pid is the group leader and a
313
+ * member that survives its leader — a `sh` wrapper killed by the stop signal while the app
314
+ * it launched keeps running, or a runner child that outlives its parent — keeps holding the
315
+ * group id while the tracked ChildProcess record is already terminal. Nothing in rollbridge
316
+ * can wait for or signal that group again, yet the group still holds the release's work.
317
+ *
318
+ * Only the stop path can know this, and it already observed the group while waiting for it to
319
+ * leave, so the group id is recorded there instead of rediscovered in `onExit`: that hook
320
+ * fires for every retired process, and a procfs scan costs ~200 ms per exit on a busy host.
321
+ * @param {number} pgid - Process group id the tracked process led.
322
+ * @returns {void}
323
+ */
324
+ markGroupOutlivedStop(pgid) {
325
+ if (this.groupOutlivedStop === pgid) return
326
+
327
+ this.groupOutlivedStop = pgid
328
+ this.heldProcessGroupCheckedAtMs = undefined
329
+ this.heldProcessGroupCount = undefined
330
+ this.logger("process group outlived its tracked process", {id: this.id, pgid})
331
+ }
332
+
333
+ /**
334
+ * Reports the process group left behind by a bounded stop, as observed right now.
335
+ *
336
+ * The record is re-verified rather than trusted forever: once the orphaned members exit, the
337
+ * group is gone and stops holding the key. Re-verification is rate-limited to
338
+ * `HELD_GROUP_RECHECK_MS` because it costs a procfs scan, and when procfs cannot answer at
339
+ * all the last known state is reported instead of guessing that the group is gone.
340
+ * @returns {HeldProcessGroup | undefined} The held group, or undefined when nothing is held.
341
+ */
342
+ currentHeldProcessGroup() {
343
+ const pgid = this.groupOutlivedStop
344
+
345
+ if (pgid === undefined) return undefined
346
+ if (this.state !== "stopped" && this.state !== "failed") return undefined
347
+
348
+ const nowMs = Date.now()
349
+
350
+ if (this.heldProcessGroupCount !== undefined && this.heldProcessGroupCheckedAtMs !== undefined && nowMs - this.heldProcessGroupCheckedAtMs < HELD_GROUP_RECHECK_MS) {
351
+ return {liveMemberCount: this.heldProcessGroupCount, pgid}
352
+ }
353
+
354
+ const sample = sampleProcessGroup(pgid)
355
+
356
+ this.heldProcessGroupCheckedAtMs = nowMs
357
+
358
+ if (sample === undefined) return {liveMemberCount: this.heldProcessGroupCount, pgid}
359
+
360
+ if (sample.memberCount === 0) {
361
+ this.groupOutlivedStop = undefined
362
+ this.heldProcessGroupCount = undefined
363
+
364
+ return undefined
365
+ }
366
+
367
+ this.heldProcessGroupCount = sample.liveMemberCount
368
+
369
+ return {liveMemberCount: sample.liveMemberCount, pgid}
370
+ }
371
+
288
372
  /**
289
373
  * Schedules an automatic restart per the restart policy, or gives up once the policy's limit is reached.
290
374
  * @returns {void}
@@ -438,8 +522,8 @@ export default class ManagedProcess extends EventEmitter {
438
522
  }
439
523
 
440
524
  /**
441
- * @param {{timeoutMs?: number}} [options] - Stop options.
442
- * @returns {Promise<void>} Resolves when stopped.
525
+ * @param {{retirementTimeoutMs?: number, timeoutMs?: number}} [options] - Stop options.
526
+ * @returns {Promise<void>} Resolves when stopped or when retirement stops waiting.
443
527
  */
444
528
  async stop(options = {}) {
445
529
  this.operationRevision += 1
@@ -448,12 +532,13 @@ export default class ManagedProcess extends EventEmitter {
448
532
  }
449
533
 
450
534
  /**
451
- * @param {{timeoutMs?: number}} options - Stop options.
452
- * @returns {Promise<void>} Resolves when stopped.
535
+ * @param {{retirementTimeoutMs?: number, timeoutMs?: number}} options - Stop options.
536
+ * @returns {Promise<void>} Resolves when stopped or when retirement stops waiting.
453
537
  */
454
538
  async performStop(options) {
455
539
  const pgid = this.child?.pid ?? this.pid
456
540
  const exitPromise = this.exitPromise
541
+ const retirementDeadline = options.retirementTimeoutMs === undefined ? undefined : Date.now() + options.retirementTimeoutMs
457
542
  await this.quiesce()
458
543
 
459
544
  if (!pgid) {
@@ -475,23 +560,43 @@ export default class ManagedProcess extends EventEmitter {
475
560
  // 3. Stop whatever is still running, then SIGKILL if it outlasts the graceful window.
476
561
  if (this.processGroupExists(pgid)) {
477
562
  const timeoutMs = options.timeoutMs ?? this.stopTimeoutMs
478
- let gracefulDeadline
563
+ const gracefulDeadline = timeoutMs === "indefinite" ? undefined : Date.now() + timeoutMs
564
+ // A retirement budget is the caller's decision that this process must not be waited for and
565
+ // must not be killed, so it caps the graceful window rather than only standing in for a
566
+ // missing one. Read the other way round, a finite `gracefulStopMs` outvotes the retirement
567
+ // bound and the wait runs for the whole window: TensorBuzz production moved its worker from
568
+ // `"indefinite"` to 4,5 h and the stop would still have held the control plane for 4,5 h.
569
+ const retirementBound = retirementDeadline !== undefined && (gracefulDeadline === undefined || retirementDeadline < gracefulDeadline)
570
+ const waitDeadline = retirementBound ? retirementDeadline : gracefulDeadline
479
571
 
480
572
  if (stopCommand) {
481
573
  await this.runHook(stopCommand, hookTimeoutMs, "stop command", pgid)
482
- gracefulDeadline = timeoutMs === "indefinite" ? undefined : Date.now() + timeoutMs
483
574
  } else {
484
575
  this.intentionalStopSignal = /** @type {ProcessExitSignal} */ (this.stopSignal)
485
- gracefulDeadline = timeoutMs === "indefinite" ? undefined : Date.now() + timeoutMs
486
- await this.signalProcessGroup(this.stopSignal, pgid, gracefulDeadline)
576
+ await this.signalProcessGroup(this.stopSignal, pgid, waitDeadline)
577
+ }
578
+
579
+ const exited = await this.waitForProcessGroupExit(pgid, waitDeadline)
580
+
581
+ if (!exited && retirementBound) {
582
+ this.retirementTimedOut = true
583
+ this.markGroupOutlivedStop(pgid)
584
+ // The tracked process has completed its supervised stop even though its process group is
585
+ // still draining. Keep the residue in heldProcessGroup rather than leaving the process
586
+ // permanently quiesced, which would make a drained generation look active to restore
587
+ // admission and keep the owner state from describing the actual stopped generation.
588
+ this.state = "stopped"
589
+ this.logger("process retirement wait timed out; leaving process alive", {id: this.id, pid: pgid, timeoutMs: options.retirementTimeoutMs})
590
+ return
487
591
  }
488
592
 
489
- if (!(await this.waitForProcessGroupExit(pgid, gracefulDeadline))) {
593
+ if (!exited) {
490
594
  this.logger("process stop timed out; sending SIGKILL", {id: this.id, pid: pgid})
491
595
  const killDeadline = Date.now() + 5000
492
596
 
493
597
  await this.signalProcessGroup("SIGKILL", pgid, killDeadline)
494
- await this.waitForProcessGroupExit(pgid, killDeadline)
598
+
599
+ if (!await this.waitForProcessGroupExit(pgid, killDeadline)) this.markGroupOutlivedStop(pgid)
495
600
  }
496
601
  }
497
602
 
@@ -500,6 +605,49 @@ export default class ManagedProcess extends EventEmitter {
500
605
  this.state = "stopped"
501
606
  }
502
607
 
608
+ /**
609
+ * Delivers the SIGKILL that retirement proved it must not wait for.
610
+ *
611
+ * Retirement deliberately leaves a non-blocking process alive: STOE-1077 measured what a
612
+ * stop-timeout kill costs when the process still holds live lanes (67 builds, 27.3
613
+ * build-hours). That is right while the process can still drain and wrong once it cannot — a
614
+ * wedged generation keeps its release open, keeps its port reservation, and makes every
615
+ * later deploy wait on it until an operator signals the exact PIDs by hand. This is the
616
+ * acting half of that decision, and it re-checks the two invariants this class owns before
617
+ * sending anything: the process must already be recorded as past its retirement budget, and
618
+ * its group must still have a member that can be signalled.
619
+ * @param {{reason: string}} options - Named evidence behind the escalation.
620
+ * @returns {Promise<boolean>} True when a live process group was signalled.
621
+ */
622
+ async escalateRetirement({reason}) {
623
+ const pgid = this.pid ?? this.groupOutlivedStop
624
+
625
+ if (pgid === undefined) return false
626
+
627
+ if (!this.retirementTimedOut) {
628
+ this.logger("retirement escalation refused; process is not past its retirement budget", {id: this.id, pid: pgid})
629
+
630
+ return false
631
+ }
632
+
633
+ if (!this.processGroupExists(pgid)) {
634
+ this.groupOutlivedStop = undefined
635
+ this.heldProcessGroupCount = undefined
636
+
637
+ return false
638
+ }
639
+
640
+ this.logger("process retirement escalated to SIGKILL", {id: this.id, pid: pgid, reason})
641
+
642
+ const killDeadline = Date.now() + ESCALATION_KILL_CONFIRM_MS
643
+
644
+ await this.signalProcessGroup("SIGKILL", pgid, killDeadline)
645
+
646
+ if (!await this.waitForProcessGroupExit(pgid, killDeadline)) this.markGroupOutlivedStop(pgid)
647
+
648
+ return true
649
+ }
650
+
503
651
  /** @returns {Promise<void>} Stops restarts and waits until the process has stopped accepting new work. */
504
652
  async quiesce() {
505
653
  if (this.quiescePromise) return await this.quiescePromise
@@ -642,6 +790,19 @@ export default class ManagedProcess extends EventEmitter {
642
790
  return this.stopTimeoutMs
643
791
  }
644
792
 
793
+ /**
794
+ * Reports whether this process's graceful window has no upper bound.
795
+ *
796
+ * `"indefinite"` is the consumer's statement that the supervisor must never kill this process;
797
+ * it is not a statement that a caller may wait for it forever. A stop that has no retirement
798
+ * budget for such a process can only hang, and when that stop runs inside an owner mutation it
799
+ * locks out every later mutation (STOE-2015).
800
+ * @returns {boolean} True when no deadline can ever end the wait.
801
+ */
802
+ hasUnboundedGracefulWindow() {
803
+ return this.stopTimeoutMs === "indefinite"
804
+ }
805
+
645
806
  /**
646
807
  * Runs a lifecycle hook command, bounded by a timeout so a hung hook can never block stop().
647
808
  * Failures are logged and returned so generation retirement can surface a failed quiet hook;
@@ -844,6 +1005,7 @@ export default class ManagedProcess extends EventEmitter {
844
1005
  cwd: this.cwd,
845
1006
  exitCode: this.exitCode,
846
1007
  exitSignal: this.exitSignal,
1008
+ heldProcessGroup: this.currentHeldProcessGroup(),
847
1009
  id: this.id,
848
1010
  lastMemoryRestartAt: this.lastMemoryRestartAtMs === undefined ? undefined : new Date(this.lastMemoryRestartAtMs).toISOString(),
849
1011
  lastStartReason: this.lastStartReason,
@@ -853,6 +1015,7 @@ export default class ManagedProcess extends EventEmitter {
853
1015
  pid: this.pid,
854
1016
  processStartTime: this.processStartTime,
855
1017
  restarts: this.restarts,
1018
+ retirementTimedOut: this.retirementTimedOut,
856
1019
  rssBytes: this.rssBytes,
857
1020
  startedAt: this.startedAtMs === undefined ? undefined : new Date(this.startedAtMs).toISOString(),
858
1021
  state: this.state,
@@ -860,3 +1023,21 @@ export default class ManagedProcess extends EventEmitter {
860
1023
  }
861
1024
  }
862
1025
  }
1026
+
1027
+ /**
1028
+ * The guardian's provenance fence, in one place: a registered child stops fencing a later
1029
+ * claim on its key only when its record is terminal *and* it holds no pid, and a process
1030
+ * group that outlived the tracked process is not gone either.
1031
+ *
1032
+ * Both the guardian (re-registering a key under a new provenance) and the daemon (restoring a
1033
+ * release that is recorded as drained) must agree on this, or a restore reaches the guardian
1034
+ * and fails there with a bare `Guardian provenance mismatch` naming a process the operator
1035
+ * cannot see in `status`.
1036
+ * @param {Pick<ManagedProcessStatus, "heldProcessGroup" | "pid" | "state">} status - Process status record.
1037
+ * @returns {boolean} True when the child is conclusively gone.
1038
+ */
1039
+ export function childRecordIsGone(status) {
1040
+ if (status.heldProcessGroup) return false
1041
+
1042
+ return (status.state === "stopped" || status.state === "failed") && status.pid === undefined
1043
+ }