lifecycleion 0.0.13 → 0.0.14

package/dist/lib/lifecycle-manager/index.cjs

@@ -1263,6 +1263,16 @@ var LifecycleManagerEvents = class {
       code: info?.code
     });
   }
+  componentStalledResolved(name, stallInfo, stalledDurationMS) {
+    this.emit("component:stalled-resolved", {
+      name,
+      stallInfo,
+      stalledDurationMS
+    });
+  }
+  componentUnexpectedStop(name, error) {
+    this.emit("component:unexpected-stop", { name, error });
+  }
   componentShutdownForceCompleted(name) {
     this.emit("component:shutdown-force-completed", { name });
   }
@@ -1449,6 +1459,25 @@ var lifecycleManagerErrCodes = {
   StopTimeout: "StopTimeout"
 };
 
+// src/lib/lifecycle-manager/constants.ts
+var LIFECYCLE_MANAGER_MESSAGE_BULK_OPERATION_IN_PROGRESS = "Cannot unregister during bulk operation";
+var LIFECYCLE_MANAGER_MESSAGE_COMPONENT_NOT_FOUND = "Component not found";
+var LIFECYCLE_MANAGER_MESSAGE_COMPONENT_NOT_RUNNING = "Component not running";
+var LIFECYCLE_MANAGER_MESSAGE_COMPONENT_STALLED = "Component is stalled";
+var LIFECYCLE_MANAGER_MESSAGE_BULK_STARTUP_IN_PROGRESS = "Bulk startup in progress";
+var LIFECYCLE_MANAGER_MESSAGE_SHUTDOWN_IN_PROGRESS = "Shutdown in progress";
+var LIFECYCLE_MANAGER_MESSAGE_UNKNOWN_ERROR = "Unknown error";
+var LIFECYCLE_MANAGER_LOG_AUTO_DETACH_LAST_COMPONENT_STOP = "Auto-detaching process signals on last component stop";
+var LIFECYCLE_MANAGER_LOG_LOGGER_EXIT_DURING_SHUTDOWN = "Logger exit called during shutdown, waiting...";
+var LIFECYCLE_MANAGER_LOG_MESSAGE_HANDLER_FAILED = "Message handler failed: {{error.message}}";
+var LIFECYCLE_MANAGER_MESSAGE_GRACEFUL_SHUTDOWN_TIMED_OUT = "Graceful shutdown timed out";
+var LIFECYCLE_MANAGER_MESSAGE_FORCE_SHUTDOWN_TIMED_OUT = "Force shutdown timed out";
+var LIFECYCLE_MANAGER_LOG_OPTIONAL_COMPONENT_UNEXPECTED_STOP_DURING_STARTUP = "Optional component stopped unexpectedly during startup, continuing: {{error.message}}";
+var LIFECYCLE_MANAGER_LOG_REQUIRED_COMPONENT_UNEXPECTED_STOP_DURING_STARTUP = "Required component stopped unexpectedly during startup: {{error.message}}";
+var LIFECYCLE_MANAGER_MESSAGE_REGISTER_SHUTDOWN_IN_PROGRESS = "Cannot register component while shutdown is in progress (isShuttingDown=true).";
+var LIFECYCLE_MANAGER_MESSAGE_REGISTER_REQUIRED_DEPENDENCY_DURING_STARTUP = "Cannot register component during startup when it is a required dependency for other components.";
+var LIFECYCLE_MANAGER_MESSAGE_DUPLICATE_COMPONENT_INSTANCE = "Component instance is already registered.";
+
 // src/lib/process-signal-manager.ts
 var import_ulid = require("ulid");
 var import_readline = __toESM(require("readline"), 1);
@@ -1993,8 +2022,15 @@ var LifecycleManager = class extends EventEmitterProtected {
   componentTimestamps = /* @__PURE__ */ new Map();
   componentErrors = /* @__PURE__ */ new Map();
   componentStartAttemptTokens = /* @__PURE__ */ new Map();
+  // Use per-stop ULIDs instead of incrementing counters because a stalled
+  // component can be unregistered and replaced by a same-name instance before
+  // the old floating stop promise settles.
+  componentStopAttemptTokens = /* @__PURE__ */ new Map();
+  pendingForceStopWaiters = /* @__PURE__ */ new Map();
+  unexpectedStopsDuringStartup = /* @__PURE__ */ new Map();
   // State flags
   isStarting = false;
+  autoAttachedSignalsDuringStartup = false;
   isStarted = false;
   isShuttingDown = false;
   // Unique token used to detect shutdowns that happened during async start().
@@ -2143,7 +2179,7 @@ var LifecycleManager = class extends EventEmitterProtected {
    */
   async unregisterComponent(name, options) {
     if (this.isStarting || this.isShuttingDown) {
-      this.logger.entity(name).warn("Cannot unregister during bulk operation", {
+      this.logger.entity(name).warn(LIFECYCLE_MANAGER_MESSAGE_BULK_OPERATION_IN_PROGRESS, {
         params: {
           isStarting: this.isStarting,
           isShuttingDown: this.isShuttingDown
@@ -2152,7 +2188,7 @@ var LifecycleManager = class extends EventEmitterProtected {
       return {
         success: false,
         componentName: name,
-        reason: "Cannot unregister during bulk operation",
+        reason: LIFECYCLE_MANAGER_MESSAGE_BULK_OPERATION_IN_PROGRESS,
         code: "bulk_operation_in_progress",
         wasStopped: false,
         wasRegistered: this.hasComponent(name)
@@ -2160,11 +2196,11 @@ var LifecycleManager = class extends EventEmitterProtected {
     }
     const component = this.getComponent(name);
     if (!component) {
-      this.logger.entity(name).warn("Component not found");
+      this.logger.entity(name).warn(LIFECYCLE_MANAGER_MESSAGE_COMPONENT_NOT_FOUND);
       return {
         success: false,
         componentName: name,
-        reason: "Component not found",
+        reason: LIFECYCLE_MANAGER_MESSAGE_COMPONENT_NOT_FOUND,
         code: "component_not_found",
         wasStopped: false,
         wasRegistered: false
@@ -2177,7 +2213,7 @@ var LifecycleManager = class extends EventEmitterProtected {
       return {
         success: false,
         componentName: name,
-        reason: "Component is stalled",
+        reason: LIFECYCLE_MANAGER_MESSAGE_COMPONENT_STALLED,
         code: "stop_failed",
         stopFailureReason: "stalled",
         wasStopped: false,
@@ -2229,10 +2265,13 @@ var LifecycleManager = class extends EventEmitterProtected {
       wasStopped = true;
     }
     this.components = this.components.filter((c) => c.getName() !== name);
+    component._clearUnexpectedStopHandler();
     this.componentStates.delete(name);
     this.componentTimestamps.delete(name);
     this.componentErrors.delete(name);
     this.componentStartAttemptTokens.delete(name);
+    this.componentStopAttemptTokens.delete(name);
+    this.pendingForceStopWaiters.delete(name);
     this.stalledComponents.delete(name);
     this.runningComponents.delete(name);
     this.updateStartedFlag();
@@ -2579,7 +2618,7 @@ var LifecycleManager = class extends EventEmitterProtected {
         startedComponents: [],
         failedOptionalComponents: [],
         skippedDueToDependency: [],
-        reason: "Shutdown in progress",
+        reason: LIFECYCLE_MANAGER_MESSAGE_SHUTDOWN_IN_PROGRESS,
         code: "shutdown_in_progress",
         durationMS: Date.now() - startTime
       };
@@ -2639,6 +2678,8 @@ var LifecycleManager = class extends EventEmitterProtected {
       };
     }
     this.isStarting = true;
+    this.autoAttachedSignalsDuringStartup = false;
+    this.unexpectedStopsDuringStartup.clear();
     this.resetRepeatedShutdownRequestState();
     this.shutdownMethod = null;
     this.lastShutdownResult = null;
@@ -2771,13 +2812,49 @@ var LifecycleManager = class extends EventEmitterProtected {
             error: result.error,
             durationMS: Date.now() - startTime
           };
+        } else if (result.code === "component_unexpected_stop") {
+          this.unexpectedStopsDuringStartup.delete(name);
+          const error = result.error || new Error(
+            result.reason || `Component "${name}" stopped unexpectedly`
+          );
+          if (component.isOptional()) {
+            if (!failedOptionalComponents.some((entry) => entry.name === name)) {
+              failedOptionalComponents.push({ name, error });
+            }
+            this.logger.entity(name).warn(
+              LIFECYCLE_MANAGER_LOG_OPTIONAL_COMPONENT_UNEXPECTED_STOP_DURING_STARTUP,
+              {
+                params: { error }
+              }
+            );
+          } else {
+            this.logger.entity(name).error(
+              LIFECYCLE_MANAGER_LOG_REQUIRED_COMPONENT_UNEXPECTED_STOP_DURING_STARTUP,
+              {
+                params: { error }
+              }
+            );
+            await this.rollbackStartup(startedComponents);
+            return {
+              success: false,
+              startedComponents: [],
+              failedOptionalComponents,
+              skippedDueToDependency: Array.from(skippedDueToDependency),
+              reason: error.message,
+              code: "component_unexpected_stop",
+              error,
+              durationMS: Date.now() - startTime
+            };
+          }
         } else {
           if (component.isOptional()) {
             this.logger.entity(name).warn(
               "Optional component failed to start, continuing: {{error.message}}",
               {
                 params: {
-                  error: result.error || new Error(result.reason || "Unknown error")
+                  error: result.error || new Error(
+                    result.reason || LIFECYCLE_MANAGER_MESSAGE_UNKNOWN_ERROR
+                  )
                 }
               }
             );
@@ -2791,14 +2868,18 @@ var LifecycleManager = class extends EventEmitterProtected {
             }
             failedOptionalComponents.push({
               name,
-              error: result.error || new Error(result.reason || "Unknown error")
+              error: result.error || new Error(
+                result.reason || LIFECYCLE_MANAGER_MESSAGE_UNKNOWN_ERROR
+              )
             });
           } else {
             this.logger.entity(name).error(
               "Required component failed to start, rolling back: {{error.message}}",
               {
                 params: {
-                  error: result.error || new Error(result.reason || "Unknown error")
+                  error: result.error || new Error(
+                    result.reason || LIFECYCLE_MANAGER_MESSAGE_UNKNOWN_ERROR
+                  )
                 }
               }
             );
@@ -2815,6 +2896,25 @@ var LifecycleManager = class extends EventEmitterProtected {
             };
           }
         }
+        const unexpectedStopResult2 = this.consumeUnexpectedStopsDuringStartup(
+          startedComponents,
+          failedOptionalComponents
+        );
+        startedComponents.splice(0, startedComponents.length);
+        startedComponents.push(...unexpectedStopResult2.startedComponents);
+        if (unexpectedStopResult2.requiredFailure) {
+          await this.rollbackStartup(startedComponents);
+          return {
+            success: false,
+            startedComponents: [],
+            failedOptionalComponents,
+            skippedDueToDependency: Array.from(skippedDueToDependency),
+            reason: unexpectedStopResult2.requiredFailure.error.message,
+            code: "component_unexpected_stop",
+            error: unexpectedStopResult2.requiredFailure.error,
+            durationMS: Date.now() - startTime
+          };
+        }
       }
       if (hasTimedOut) {
         const durationMS2 = Date.now() - startTime;
@@ -2838,6 +2938,25 @@ var LifecycleManager = class extends EventEmitterProtected {
           code: "startup_timeout"
         };
       }
+      const unexpectedStopResult = this.consumeUnexpectedStopsDuringStartup(
+        startedComponents,
+        failedOptionalComponents
+      );
+      startedComponents.splice(0, startedComponents.length);
+      startedComponents.push(...unexpectedStopResult.startedComponents);
+      if (unexpectedStopResult.requiredFailure) {
+        await this.rollbackStartup(startedComponents);
+        return {
+          success: false,
+          startedComponents: [],
+          failedOptionalComponents,
+          skippedDueToDependency: Array.from(skippedDueToDependency),
+          reason: unexpectedStopResult.requiredFailure.error.message,
+          code: "component_unexpected_stop",
+          error: unexpectedStopResult.requiredFailure.error,
+          durationMS: Date.now() - startTime
+        };
+      }
       this.updateStartedFlag();
       const skippedComponentsArray = [
         ...Array.from(skippedDueToDependency),
@@ -2869,10 +2988,12 @@ var LifecycleManager = class extends EventEmitterProtected {
       if (timeoutHandle) {
         clearTimeout(timeoutHandle);
       }
-      if (didAutoAttachSignalsForBulkStartup) {
+      this.isStarting = false;
+      if (didAutoAttachSignalsForBulkStartup || this.autoAttachedSignalsDuringStartup) {
         this.autoDetachSignalsIfIdle("failed bulk startup");
       }
-      this.isStarting = false;
+      this.autoAttachedSignalsDuringStartup = false;
+      this.unexpectedStopsDuringStartup.clear();
     }
   }
   /**
@@ -2936,7 +3057,7 @@ var LifecycleManager = class extends EventEmitterProtected {
       return {
         success: false,
         componentName: name,
-        reason: "Bulk startup in progress",
+        reason: LIFECYCLE_MANAGER_MESSAGE_BULK_STARTUP_IN_PROGRESS,
         code: "startup_in_progress"
       };
     }
@@ -2947,7 +3068,7 @@ var LifecycleManager = class extends EventEmitterProtected {
       return {
         success: false,
         componentName: name,
-        reason: "Shutdown in progress",
+        reason: LIFECYCLE_MANAGER_MESSAGE_SHUTDOWN_IN_PROGRESS,
         code: "shutdown_in_progress"
       };
     }
@@ -2981,7 +3102,7 @@ var LifecycleManager = class extends EventEmitterProtected {
       return {
         success: false,
         componentName: name,
-        reason: this.isStarting ? "Bulk startup in progress" : "Shutdown in progress",
+        reason: this.isStarting ? LIFECYCLE_MANAGER_MESSAGE_BULK_STARTUP_IN_PROGRESS : LIFECYCLE_MANAGER_MESSAGE_SHUTDOWN_IN_PROGRESS,
         code: this.isStarting ? "startup_in_progress" : "shutdown_in_progress"
       };
     }
@@ -3163,7 +3284,7 @@ var LifecycleManager = class extends EventEmitterProtected {
         if (this.isShuttingDown) {
           if (isFirstExit && this.pendingLoggerExitResolve === null) {
             this.logger.debug(
-              "Logger exit called during shutdown, waiting...",
+              LIFECYCLE_MANAGER_LOG_LOGGER_EXIT_DURING_SHUTDOWN,
               {
                 params: { exitCode }
               }
@@ -3172,7 +3293,7 @@ var LifecycleManager = class extends EventEmitterProtected {
               this.pendingLoggerExitResolve = resolve;
             });
           }
-          this.logger.debug("Logger exit called during shutdown, waiting...", {
+          this.logger.debug(LIFECYCLE_MANAGER_LOG_LOGGER_EXIT_DURING_SHUTDOWN, {
             params: { exitCode }
           });
           return { action: "wait" };
@@ -3262,7 +3383,7 @@ var LifecycleManager = class extends EventEmitterProtected {
       return {
         name,
         healthy: false,
-        message: "Component not found",
+        message: LIFECYCLE_MANAGER_MESSAGE_COMPONENT_NOT_FOUND,
         checkedAt: startTime,
         durationMS: 0,
         error: null,
@@ -3275,7 +3396,7 @@ var LifecycleManager = class extends EventEmitterProtected {
       return {
         name,
         healthy: false,
-        message: isStalled ? "Component is stalled" : "Component not running",
+        message: isStalled ? LIFECYCLE_MANAGER_MESSAGE_COMPONENT_STALLED : LIFECYCLE_MANAGER_MESSAGE_COMPONENT_NOT_RUNNING,
         checkedAt: startTime,
         durationMS: Date.now() - startTime,
         error: null,
@@ -3491,7 +3612,7 @@ var LifecycleManager = class extends EventEmitterProtected {
         result = component.onMessage(payload, from);
       } catch (error) {
         const err = error instanceof Error ? error : new Error(String(error));
-        this.logger.entity(componentName).error("Message handler failed: {{error.message}}", {
+        this.logger.entity(componentName).error(LIFECYCLE_MANAGER_LOG_MESSAGE_HANDLER_FAILED, {
           params: { error: err, from }
         });
         this.lifecycleEvents.componentMessageFailed(componentName, from, err, {
@@ -3551,7 +3672,7 @@ var LifecycleManager = class extends EventEmitterProtected {
       };
     } catch (error) {
       const err = error instanceof Error ? error : new Error(String(error));
-      this.logger.entity(componentName).error("Message handler failed: {{error.message}}", {
+      this.logger.entity(componentName).error(LIFECYCLE_MANAGER_LOG_MESSAGE_HANDLER_FAILED, {
         params: { error: err, from, timeoutMS }
       });
       this.lifecycleEvents.componentMessageFailed(componentName, from, err, {
@@ -3824,7 +3945,7 @@ var LifecycleManager = class extends EventEmitterProtected {
         this.lifecycleEvents.componentRegistrationRejected({
           name: componentName,
           reason: "shutdown_in_progress",
-          message: "Cannot register component while shutdown is in progress (isShuttingDown=true).",
+          message: LIFECYCLE_MANAGER_MESSAGE_REGISTER_SHUTDOWN_IN_PROGRESS,
           registrationIndexBefore,
           registrationIndexAfter: registrationIndexBefore,
           requestedPosition: isInsertAction ? { position, targetComponentName } : void 0,
@@ -3836,7 +3957,7 @@ var LifecycleManager = class extends EventEmitterProtected {
           targetComponentName,
           registrationIndexBefore,
           code: "shutdown_in_progress",
-          reason: "Cannot register component while shutdown is in progress (isShuttingDown=true).",
+          reason: LIFECYCLE_MANAGER_MESSAGE_REGISTER_SHUTDOWN_IN_PROGRESS,
           targetFound: void 0
         });
       }
@@ -3847,7 +3968,7 @@ var LifecycleManager = class extends EventEmitterProtected {
         this.lifecycleEvents.componentRegistrationRejected({
           name: componentName,
           reason: "startup_in_progress",
-          message: "Cannot register component during startup when it is a required dependency for other components.",
+          message: LIFECYCLE_MANAGER_MESSAGE_REGISTER_REQUIRED_DEPENDENCY_DURING_STARTUP,
           registrationIndexBefore,
           registrationIndexAfter: registrationIndexBefore,
           requestedPosition: isInsertAction ? { position, targetComponentName } : void 0,
@@ -3859,7 +3980,7 @@ var LifecycleManager = class extends EventEmitterProtected {
           targetComponentName,
           registrationIndexBefore,
           code: "startup_in_progress",
-          reason: "Cannot register component during startup when it is a required dependency for other components.",
+          reason: LIFECYCLE_MANAGER_MESSAGE_REGISTER_REQUIRED_DEPENDENCY_DURING_STARTUP,
           targetFound: void 0
         });
       }
@@ -3868,7 +3989,7 @@ var LifecycleManager = class extends EventEmitterProtected {
         this.lifecycleEvents.componentRegistrationRejected({
           name: componentName,
           reason: "duplicate_instance",
-          message: "Component instance is already registered.",
+          message: LIFECYCLE_MANAGER_MESSAGE_DUPLICATE_COMPONENT_INSTANCE,
           registrationIndexBefore,
           registrationIndexAfter: registrationIndexBefore,
           requestedPosition: isInsertAction ? { position, targetComponentName } : void 0,
@@ -3880,7 +4001,7 @@ var LifecycleManager = class extends EventEmitterProtected {
           targetComponentName,
           registrationIndexBefore,
           code: "duplicate_instance",
-          reason: "Component instance is already registered.",
+          reason: LIFECYCLE_MANAGER_MESSAGE_DUPLICATE_COMPONENT_INSTANCE,
           targetFound: void 0
         });
       }
@@ -4194,8 +4315,7 @@ var LifecycleManager = class extends EventEmitterProtected {
     const runningComponentsToStop = shutdownOrder.filter(
       (name) => this.isComponentRunning(name) || shouldRetryStalled && stalledComponentNames.has(name)
     );
-    const stoppedComponents = [];
-    const stalledComponents = [];
+    const stoppedComponents = /* @__PURE__ */ new Set();
     let hasTimedOut = false;
     let timeoutHandle;
     try {
@@ -4226,34 +4346,37 @@ var LifecycleManager = class extends EventEmitterProtected {
           this.logger.entity(name).info("Stopping component");
           const isRunning = this.isComponentRunning(name);
           const isStalled = stalledComponentNames.has(name);
+          const currentState = this.componentStates.get(name);
+          if (currentState === "stopped") {
+            stoppedComponents.add(name);
+            continue;
+          }
           const result2 = isRunning ? await this.stopComponentInternal(name) : shouldRetryStalled && isStalled ? await this.retryStalledComponent(name) : isStalled ? {
             success: false,
             componentName: name,
-            reason: "Component is stalled",
+            reason: LIFECYCLE_MANAGER_MESSAGE_COMPONENT_STALLED,
             code: "component_stalled",
             status: this.getComponentStatus(name)
           } : {
             success: false,
             componentName: name,
-            reason: "Component not running",
+            reason: LIFECYCLE_MANAGER_MESSAGE_COMPONENT_NOT_RUNNING,
             code: "component_not_running",
             status: this.getComponentStatus(name)
           };
           if (result2.success) {
-            stoppedComponents.push(name);
+            stoppedComponents.add(name);
           } else {
             this.logger.entity(name).error(
               "Component failed to stop, continuing with others: {{error.message}}",
               {
                 params: {
-                  error: result2.error || new Error(result2.reason || "Unknown error")
+                  error: result2.error || new Error(
+                    result2.reason || LIFECYCLE_MANAGER_MESSAGE_UNKNOWN_ERROR
+                  )
                 }
               }
             );
-            const stallInfo = this.stalledComponents.get(name);
-            if (stallInfo) {
-              stalledComponents.push(stallInfo);
-            }
             if (shouldHaltOnStall) {
               this.logger.warn(
                 "Halting shutdown after stall (haltOnStall=true)",
@@ -4269,21 +4392,32 @@ var LifecycleManager = class extends EventEmitterProtected {
       } else {
         await shutdownOperation();
       }
+      const finalStalledNames = /* @__PURE__ */ new Set();
+      for (const name of runningComponentsToStop) {
+        if (this.stalledComponents.has(name)) {
+          finalStalledNames.add(name);
+        }
+      }
       if (!shouldRetryStalled) {
         for (const name of stalledComponentNames) {
-          const stallInfo = this.stalledComponents.get(name);
-          if (stallInfo && !stalledComponents.some((component) => component.name === name)) {
-            stalledComponents.push(stallInfo);
+          if (this.stalledComponents.has(name)) {
+            finalStalledNames.add(name);
           }
         }
       }
+      for (const name of runningComponentsToStop) {
+        if (!finalStalledNames.has(name) && this.componentStates.get(name) === "stopped") {
+          stoppedComponents.add(name);
+        }
+      }
+      const stalledComponents = Array.from(finalStalledNames).map((name) => this.stalledComponents.get(name)).filter((stallInfo) => !!stallInfo);
       const durationMS = Date.now() - startTime;
       const isSuccess = !hasTimedOut && stalledComponents.length === 0;
       this.logger[isSuccess ? "success" : "warn"](
         isSuccess ? "Shutdown completed successfully" : "Shutdown attempt completed with stalled components or timeout",
         {
           params: {
-            stopped: stoppedComponents.length,
+            stopped: stoppedComponents.size,
             stalled: stalledComponents.length,
             durationMS
           }
@@ -4291,7 +4425,7 @@ var LifecycleManager = class extends EventEmitterProtected {
       );
       const result = {
         success: isSuccess,
-        stoppedComponents,
+        stoppedComponents: Array.from(stoppedComponents),
         stalledComponents,
         durationMS,
         timedOut: hasTimedOut || void 0,
@@ -4342,7 +4476,7 @@ var LifecycleManager = class extends EventEmitterProtected {
       return {
         success: false,
         componentName: name,
-        reason: "Component not found",
+        reason: LIFECYCLE_MANAGER_MESSAGE_COMPONENT_NOT_FOUND,
         code: "component_not_found"
       };
     }
@@ -4353,12 +4487,15 @@ var LifecycleManager = class extends EventEmitterProtected {
       return {
         success: false,
         componentName: name,
-        reason: "Component not running",
+        reason: LIFECYCLE_MANAGER_MESSAGE_COMPONENT_NOT_RUNNING,
         code: "component_not_running",
         status: this.getComponentStatus(name)
       };
     }
     this.logger.entity(name).warn("Retrying stalled component shutdown (force phase)");
+    if (component.onShutdownForce) {
+      this.issueStopAttemptToken(name);
+    }
     return this.shutdownComponentForce(name, component, {
       gracefulPhaseRan: false,
       gracefulTimedOut: false,
@@ -4378,7 +4515,7 @@ var LifecycleManager = class extends EventEmitterProtected {
       return {
         success: false,
         componentName: name,
-        reason: "Shutdown in progress",
+        reason: LIFECYCLE_MANAGER_MESSAGE_SHUTDOWN_IN_PROGRESS,
         code: "shutdown_in_progress"
       };
     }
@@ -4390,7 +4527,7 @@ var LifecycleManager = class extends EventEmitterProtected {
       return {
         success: false,
         componentName: name,
-        reason: "Bulk startup in progress",
+        reason: LIFECYCLE_MANAGER_MESSAGE_BULK_STARTUP_IN_PROGRESS,
         code: "startup_in_progress"
       };
     }
@@ -4400,7 +4537,7 @@ var LifecycleManager = class extends EventEmitterProtected {
       return {
         success: false,
         componentName: name,
-        reason: "Component not found",
+        reason: LIFECYCLE_MANAGER_MESSAGE_COMPONENT_NOT_FOUND,
         code: "component_not_found"
       };
     }
@@ -4409,7 +4546,7 @@ var LifecycleManager = class extends EventEmitterProtected {
       return {
         success: false,
         componentName: name,
-        reason: "Component is stalled",
+        reason: LIFECYCLE_MANAGER_MESSAGE_COMPONENT_STALLED,
         code: "component_stalled",
         status: this.getComponentStatus(name)
       };
@@ -4473,6 +4610,9 @@ var LifecycleManager = class extends EventEmitterProtected {
     const timeoutMS = component.startupTimeoutMS;
     const startAttemptToken = (0, import_ulid2.ulid)();
     this.componentStartAttemptTokens.set(name, startAttemptToken);
+    component._setUnexpectedStopHandler(
+      (error) => this.handleComponentUnexpectedStop(name, startAttemptToken, error)
+    );
     const shutdownTokenAtStart = this.shutdownToken;
     const didAutoAttachSignalsForComponentStartup = this.attachSignalsBeforeStartup ? this.autoAttachSignals("component startup") : false;
     let timeoutHandle;
@@ -4515,6 +4655,18 @@ var LifecycleManager = class extends EventEmitterProtected {
       } else {
         await startPromise;
       }
+      if (this.componentStartAttemptTokens.get(name) === startAttemptToken && this.componentStates.get(name) === "stopped" && !this.runningComponents.has(name)) {
+        component._clearUnexpectedStopHandler();
+        const error = this.componentErrors.get(name) ?? new Error(`Component "${name}" stopped unexpectedly during startup`);
+        return {
+          success: false,
+          componentName: name,
+          reason: error.message,
+          code: "component_unexpected_stop",
+          error,
+          status: this.getComponentStatus(name)
+        };
+      }
       if (this.isShuttingDown || shutdownTokenAtStart !== this.shutdownToken) {
         this.componentStates.set(name, "running");
         this.runningComponents.add(name);
@@ -4542,6 +4694,9 @@ var LifecycleManager = class extends EventEmitterProtected {
       this.componentStates.set(name, "running");
       this.runningComponents.add(name);
       this.stalledComponents.delete(name);
+      if (shouldForceStalled) {
+        this.issueStopAttemptToken(name);
+      }
       this.updateStartedFlag();
       if (this.attachSignalsOnStart && this.runningComponents.size === 1) {
         this.autoAttachSignals("first component start");
@@ -4561,9 +4716,24 @@ var LifecycleManager = class extends EventEmitterProtected {
         status: this.getComponentStatus(name)
       };
     } catch (error) {
+      component._clearUnexpectedStopHandler();
       const err = error instanceof Error ? error : new Error(String(error));
+      const isStartupTimeout = err instanceof ComponentStartTimeoutError && err.additionalInfo.componentName === name;
+      const unexpectedStopError = this.componentErrors.get(name);
+      if (this.componentStartAttemptTokens.get(name) === startAttemptToken && this.componentStates.get(name) === "stopped" && !this.runningComponents.has(name) && (isStartupTimeout || unexpectedStopError instanceof Error)) {
+        return {
+          success: false,
+          componentName: name,
+          reason: unexpectedStopError?.message || `Component "${name}" stopped unexpectedly during startup`,
+          code: "component_unexpected_stop",
+          error: unexpectedStopError || new Error(
+            `Component "${name}" stopped unexpectedly during startup`
+          ),
+          status: this.getComponentStatus(name)
+        };
+      }
       this.componentErrors.set(name, err);
-      if (err instanceof ComponentStartTimeoutError && err.additionalInfo.componentName === name) {
+      if (isStartupTimeout) {
         this.componentStates.set(name, "starting-timed-out");
         this.logger.entity(name).error("Component startup timed out: {{error.message}}", {
           params: { error: err }
@@ -4608,7 +4778,7 @@ var LifecycleManager = class extends EventEmitterProtected {
       return {
         success: false,
         componentName: name,
-        reason: "Component not found",
+        reason: LIFECYCLE_MANAGER_MESSAGE_COMPONENT_NOT_FOUND,
         code: "component_not_found"
       };
     }
@@ -4616,7 +4786,7 @@ var LifecycleManager = class extends EventEmitterProtected {
       return {
         success: false,
         componentName: name,
-        reason: "Component is stalled",
+        reason: LIFECYCLE_MANAGER_MESSAGE_COMPONENT_STALLED,
         code: "component_stalled",
         status: this.getComponentStatus(name)
       };
@@ -4625,7 +4795,7 @@ var LifecycleManager = class extends EventEmitterProtected {
       return {
         success: false,
         componentName: name,
-        reason: "Component not running",
+        reason: LIFECYCLE_MANAGER_MESSAGE_COMPONENT_NOT_RUNNING,
         code: "component_not_running",
         status: this.getComponentStatus(name)
       };
@@ -4641,6 +4811,10 @@ var LifecycleManager = class extends EventEmitterProtected {
       };
     }
     if (options?.forceImmediate) {
+      if (component.onShutdownForce) {
+        this.issueStopAttemptToken(name);
+      }
+      component._clearUnexpectedStopHandler();
       return this.shutdownComponentForce(name, component, {
         gracefulPhaseRan: false,
         gracefulTimedOut: false,
@@ -4777,9 +4951,11 @@ var LifecycleManager = class extends EventEmitterProtected {
    * Calls stop() with timeout
    */
   async shutdownComponentGraceful(name, component, options) {
+    component._clearUnexpectedStopHandler();
     this.componentStates.set(name, "stopping");
     this.logger.entity(name).info("Graceful shutdown started");
     this.lifecycleEvents.componentStopping(name);
+    const stopAttemptToken = this.issueStopAttemptToken(name);
     const timeoutMS = options?.timeout ?? component.shutdownGracefulTimeoutMS;
     let timeoutHandle;
     try {
@@ -4800,7 +4976,16 @@ var LifecycleManager = class extends EventEmitterProtected {
                 );
               }
             }
-            Promise.resolve(stopPromise).catch(() => {
+            Promise.resolve(stopPromise).then(
+              () => this.handleLateStopResolution(
+                name,
+                stopAttemptToken,
+                "graceful"
+              ),
+              () => {
+              }
+              // Intentionally ignore errors after timeout
+            ).catch(() => {
             });
             reject(
               new ComponentStopTimeoutError({
@@ -4819,9 +5004,7 @@ var LifecycleManager = class extends EventEmitterProtected {
       this.stalledComponents.delete(name);
       this.updateStartedFlag();
       if (this.detachSignalsOnStop && this.runningComponents.size === 0 && this.processSignalManager) {
-        this.logger.info(
-          "Auto-detaching process signals on last component stop"
-        );
+        this.logger.info(LIFECYCLE_MANAGER_LOG_AUTO_DETACH_LAST_COMPONENT_STOP);
         this.detachSignals();
       }
       const timestamps = this.componentTimestamps.get(name) ?? {
@@ -4844,15 +5027,15 @@ var LifecycleManager = class extends EventEmitterProtected {
       const err = error instanceof Error ? error : new Error(String(error));
       this.componentErrors.set(name, err);
       if (err instanceof ComponentStopTimeoutError && err.additionalInfo.componentName === name) {
-        this.logger.entity(name).warn("Graceful shutdown timed out");
+        this.logger.entity(name).warn(LIFECYCLE_MANAGER_MESSAGE_GRACEFUL_SHUTDOWN_TIMED_OUT);
         this.lifecycleEvents.componentStopTimeout(name, err, {
           timeoutMS,
-          reason: "Graceful shutdown timed out"
+          reason: LIFECYCLE_MANAGER_MESSAGE_GRACEFUL_SHUTDOWN_TIMED_OUT
         });
         return {
           success: false,
           componentName: name,
-          reason: "Graceful shutdown timed out",
+          reason: LIFECYCLE_MANAGER_MESSAGE_GRACEFUL_SHUTDOWN_TIMED_OUT,
           code: "component_shutdown_timeout",
           error: err,
           status: this.getComponentStatus(name)
@@ -4895,8 +5078,6 @@ var LifecycleManager = class extends EventEmitterProtected {
         gracefulTimedOut: context.gracefulTimedOut
       }
     });
-    const timeoutMS = component.shutdownForceTimeoutMS;
-    let timeoutHandle;
     if (!component.onShutdownForce) {
       const stallInfo = {
         name,
@@ -4930,6 +5111,9 @@ var LifecycleManager = class extends EventEmitterProtected {
         status: this.getComponentStatus(name)
       };
     }
+    const timeoutMS = component.shutdownForceTimeoutMS;
+    const { promise: stoppedDuringForcePromise, cleanup: cleanupForceWaiter } = this.createPendingForceStopWaiter(name);
+    let timeoutHandle;
     try {
       const forcePromise = component.onShutdownForce();
       if (timeoutMS > 0) {
@@ -4948,23 +5132,44 @@ var LifecycleManager = class extends EventEmitterProtected {
                 );
               }
             }
-            Promise.resolve(forcePromise).catch(() => {
+            const forceAttemptToken = this.componentStopAttemptTokens.get(name) ?? (0, import_ulid2.ulid)();
+            Promise.resolve(forcePromise).then(
+              () => this.handleLateStopResolution(
+                name,
+                forceAttemptToken,
+                "force"
+              ),
+              () => {
+              }
+              // Intentionally ignore errors after timeout
+            ).catch(() => {
             });
-            reject(new Error("Force shutdown timed out"));
+            reject(
+              new Error(LIFECYCLE_MANAGER_MESSAGE_FORCE_SHUTDOWN_TIMED_OUT)
+            );
           }, timeoutMS);
         });
-        await Promise.race([forcePromise, timeoutPromise]);
+        await Promise.race([
+          forcePromise,
+          timeoutPromise,
+          stoppedDuringForcePromise
+        ]);
       } else {
-        await forcePromise;
+        await Promise.race([forcePromise, stoppedDuringForcePromise]);
+      }
+      if (this.componentStates.get(name) === "stopped" && !this.runningComponents.has(name)) {
+        return {
+          success: true,
+          componentName: name,
+          status: this.getComponentStatus(name)
+        };
       }
       this.componentStates.set(name, "stopped");
       this.runningComponents.delete(name);
       this.stalledComponents.delete(name);
       this.updateStartedFlag();
       if (this.detachSignalsOnStop && this.runningComponents.size === 0 && this.processSignalManager) {
-        this.logger.info(
-          "Auto-detaching process signals on last component stop"
-        );
+        this.logger.info(LIFECYCLE_MANAGER_LOG_AUTO_DETACH_LAST_COMPONENT_STOP);
         this.detachSignals();
       }
       const timestamps = this.componentTimestamps.get(name) ?? {
@@ -4985,8 +5190,15 @@ var LifecycleManager = class extends EventEmitterProtected {
         status: this.getComponentStatus(name)
       };
     } catch (error) {
+      if (this.componentStates.get(name) === "stopped" && !this.runningComponents.has(name)) {
+        return {
+          success: true,
+          componentName: name,
+          status: this.getComponentStatus(name)
+        };
+      }
       const err = error instanceof Error ? error : new Error(String(error));
-      const isTimeout = err.message === "Force shutdown timed out";
+      const isTimeout = err.message === LIFECYCLE_MANAGER_MESSAGE_FORCE_SHUTDOWN_TIMED_OUT;
       const stallInfo = {
         name,
         phase: "force",
@@ -5017,12 +5229,13 @@ var LifecycleManager = class extends EventEmitterProtected {
       return {
         success: false,
         componentName: name,
-        reason: isTimeout ? "Force shutdown timed out" : err.message,
+        reason: isTimeout ? LIFECYCLE_MANAGER_MESSAGE_FORCE_SHUTDOWN_TIMED_OUT : err.message,
         code: isTimeout ? "component_shutdown_timeout" : "unknown_error",
         error: err,
         status: this.getComponentStatus(name)
       };
     } finally {
+      cleanupForceWaiter();
       if (timeoutHandle) {
         clearTimeout(timeoutHandle);
       }
@@ -5099,7 +5312,9 @@ var LifecycleManager = class extends EventEmitterProtected {
           "Failed to stop component during rollback, continuing: {{error.message}}",
           {
             params: {
-              error: result.error || new Error(result.reason || "Unknown error")
+              error: result.error || new Error(
+                result.reason || LIFECYCLE_MANAGER_MESSAGE_UNKNOWN_ERROR
+              )
             }
           }
         );
@@ -5113,10 +5328,13 @@ var LifecycleManager = class extends EventEmitterProtected {
     }
     this.logger.info(`Auto-attaching process signals on ${trigger}`);
     this.attachSignals();
+    if (this.isStarting) {
+      this.autoAttachedSignalsDuringStartup = true;
+    }
     return true;
   }
   autoDetachSignalsIfIdle(trigger) {
-    if (!this.detachSignalsOnStop || this.runningComponents.size > 0 || !this.processSignalManager?.getStatus().isAttached) {
+    if (!this.detachSignalsOnStop || this.isStarting || this.runningComponents.size > 0 || !this.processSignalManager?.getStatus().isAttached) {
       return;
     }
     this.logger.info(`Auto-detaching process signals after ${trigger}`);
@@ -5158,6 +5376,210 @@ var LifecycleManager = class extends EventEmitterProtected {
     }).catch(() => {
     });
   }
+  consumeUnexpectedStopsDuringStartup(startedComponents, failedOptionalComponents) {
+    if (this.unexpectedStopsDuringStartup.size === 0) {
+      return { startedComponents: [...startedComponents] };
+    }
+    const remainingStartedComponents = [];
+    let requiredFailure;
+    for (const name of startedComponents) {
+      const startupStopError = this.unexpectedStopsDuringStartup.get(name);
+      if (startupStopError === void 0) {
+        remainingStartedComponents.push(name);
+        continue;
+      }
+      this.unexpectedStopsDuringStartup.delete(name);
+      const error = startupStopError ?? new Error(`Component "${name}" stopped unexpectedly during startup`);
+      const component = this.getComponent(name);
+      if (component?.isOptional()) {
+        if (!failedOptionalComponents.some((entry) => entry.name === name)) {
+          failedOptionalComponents.push({ name, error });
+        }
+        this.logger.entity(name).warn(
+          LIFECYCLE_MANAGER_LOG_OPTIONAL_COMPONENT_UNEXPECTED_STOP_DURING_STARTUP,
+          {
+            params: { error }
+          }
+        );
+        continue;
+      }
+      this.logger.entity(name).error(
+        LIFECYCLE_MANAGER_LOG_REQUIRED_COMPONENT_UNEXPECTED_STOP_DURING_STARTUP,
+        {
+          params: { error }
+        }
+      );
+      requiredFailure ??= { name, error };
+    }
+    return {
+      startedComponents: remainingStartedComponents,
+      requiredFailure
+    };
+  }
+  /**
+   * Issues and returns a unique stop attempt token for a component.
+   *
+   * Each stop attempt (graceful or force-retry) gets a unique token.
+   * The late-resolution handler captures this token in its closure so it can
+   * skip any stall entries that were created by a *later* stop attempt — e.g. a
+   * force-retry that also timed out after the original graceful promise floated
+   * in the background.
+   */
+  issueStopAttemptToken(name) {
+    const next = (0, import_ulid2.ulid)();
+    this.componentStopAttemptTokens.set(name, next);
+    return next;
+  }
+  createPendingForceStopWaiter(name) {
+    let isResolved = false;
+    let waiters = this.pendingForceStopWaiters.get(name);
+    if (!waiters) {
+      waiters = /* @__PURE__ */ new Set();
+      this.pendingForceStopWaiters.set(name, waiters);
+    }
+    let resolveWaiter;
+    const promise = new Promise((resolve) => {
+      resolveWaiter = () => {
+        if (isResolved) {
+          return;
+        }
+        isResolved = true;
+        resolve();
+      };
+    });
+    waiters.add(resolveWaiter);
+    return {
+      promise,
+      cleanup: () => {
+        const pending = this.pendingForceStopWaiters.get(name);
+        if (!pending) {
+          return;
+        }
+        pending.delete(resolveWaiter);
+        if (pending.size === 0) {
+          this.pendingForceStopWaiters.delete(name);
+        }
+      }
+    };
+  }
+  resolvePendingForceStopWaiters(name) {
+    const waiters = this.pendingForceStopWaiters.get(name);
+    if (!waiters || waiters.size === 0) {
+      return;
+    }
+    this.pendingForceStopWaiters.delete(name);
+    for (const resolve of waiters) {
+      resolve();
+    }
+  }
+  /**
+   * Called when a stop promise eventually resolves after its timeout path already fired.
+   *
+   * Usually this means a previously stalled component's original stop() or
+   * onShutdownForce() promise finally resolved, so the manager can clear the
+   * stall and transition the component to stopped without a manual retry.
+   *
+   * There is one extra overlap case for graceful stop(): stop() can resolve
+   * after the graceful timeout but before onShutdownForce() itself times out.
+   * In that window no stall entry exists yet, but the component still finished
+   * stopping cleanly, so we finalize it here and let the later force-timeout
+   * path observe the already-stopped state and no-op. This overlap fix is
+   * scoped to the same stop token and will not cross a later retry attempt.
+   *
+   * Two guards prevent stale floating promises from incorrectly clearing state:
+   *
+   * 1. token guard — if a newer stop attempt (e.g. a retryStalled
+   *    force-retry) has started since this promise was launched, its token
+   *    won't match and we bail out immediately.
+   *
+   * 2. state/stall guard — if the component was unregistered, restarted, or
+   *    already cleared by another path, there will be neither a matching stall
+   *    entry nor the force-phase overlap state, so we bail out.
+   */
+  handleLateStopResolution(name, token, source) {
+    if (this.componentStopAttemptTokens.get(name) !== token) {
+      return;
+    }
+    const currentState = this.componentStates.get(name);
+    const stallInfo = this.stalledComponents.get(name);
+    const isCompletedDuringForcePhase = source === "graceful" && !stallInfo && currentState === "force-stopping";
+    if (stallInfo && currentState !== "stalled") {
+      this.stalledComponents.delete(name);
+      return;
+    }
+    if (!stallInfo && !isCompletedDuringForcePhase) {
+      return;
+    }
+    const stalledDurationMS = stallInfo ? Date.now() - stallInfo.stalledAt : void 0;
+    if (stallInfo) {
+      this.stalledComponents.delete(name);
+    }
+    this.componentStates.set(name, "stopped");
+    this.runningComponents.delete(name);
+    this.componentErrors.set(name, null);
+    this.updateStartedFlag();
+    this.resolvePendingForceStopWaiters(name);
+    if (this.detachSignalsOnStop && this.runningComponents.size === 0 && this.processSignalManager) {
+      this.logger.info(LIFECYCLE_MANAGER_LOG_AUTO_DETACH_LAST_COMPONENT_STOP);
+      this.detachSignals();
+    }
+    const timestamps = this.componentTimestamps.get(name) ?? {
+      startedAt: null,
+      stoppedAt: null
+    };
+    timestamps.stoppedAt = Date.now();
+    this.componentTimestamps.set(name, timestamps);
+    this.logger.entity(name).info(
+      stallInfo ? "Stalled component completed stop late, stall cleared" : "Graceful stop completed after force phase started",
+      stalledDurationMS ? { params: { stalledDurationMS } } : void 0
+    );
+    if (source === "force") {
+      this.lifecycleEvents.componentShutdownForceCompleted(name);
+    }
+    if (stallInfo && stalledDurationMS !== void 0) {
+      this.lifecycleEvents.componentStalledResolved(
+        name,
+        stallInfo,
+        stalledDurationMS
+      );
+    }
+    this.lifecycleEvents.componentStopped(name, this.getComponentStatus(name));
+  }
+  handleComponentUnexpectedStop(name, startAttemptToken, error) {
+    const currentState = this.componentStates.get(name);
+    if (
+      // Startup-time self-stops are valid too: start() may still be awaiting
+      // some async work while an internal listener has already observed that
+      // the component died and reported it.
+      currentState !== "starting" && currentState !== "running" || this.componentStartAttemptTokens.get(name) !== startAttemptToken
+    ) {
+      return false;
+    }
+    this.runningComponents.delete(name);
+    this.componentStates.set(name, "stopped");
+    this.componentErrors.set(name, error ?? null);
+    if (this.isStarting) {
+      this.unexpectedStopsDuringStartup.set(name, error ?? null);
+    }
+    this.updateStartedFlag();
+    if (this.detachSignalsOnStop && !this.isStarting && this.runningComponents.size === 0 && this.processSignalManager) {
+      this.logger.info(LIFECYCLE_MANAGER_LOG_AUTO_DETACH_LAST_COMPONENT_STOP);
+      this.detachSignals();
+    }
+    const timestamps = this.componentTimestamps.get(name) ?? {
+      startedAt: null,
+      stoppedAt: null
+    };
+    timestamps.stoppedAt = Date.now();
+    this.componentTimestamps.set(name, timestamps);
+    this.logger.entity(name).warn(
+      error ? `Component stopped unexpectedly: ${error.message}` : "Component stopped unexpectedly",
+      { params: { error } }
+    );
+    this.lifecycleEvents.componentUnexpectedStop(name, error);
+    this.lifecycleEvents.componentStopped(name, this.getComponentStatus(name));
+    return true;
+  }
   /**
    * Safe emit wrapper - prevents event handler errors from breaking lifecycle
    */
@@ -5729,105 +6151,87 @@ var LifecycleManager = class extends EventEmitterProtected {
     }
   }
   /**
-   * Handle reload request - calls custom callback or broadcasts to components.
+   * Shared dispatch path for reload/info/debug requests. Logs the dispatch,
+   * emits the signal event, then either invokes the user-supplied callback
+   * (passing the broadcast function so the user controls when/whether to
+   * broadcast) or broadcasts directly when no callback is configured.
    *
    * When called from signal handlers (source='signal'), the Promise is started
-   * but not awaited due to Node.js signal handler constraints. Components are
-   * still notified and the work completes, but return values are not accessible.
-   *
+   * but not awaited — Node.js signal handlers cannot return values, so results
+   * are not accessible. Components are still notified and the work completes.
    * When called from manual triggers (source='trigger'), the Promise is awaited
    * and results are returned for programmatic use.
-   *
-   * @param source - Whether triggered from signal manager or manual trigger
    */
-  async handleReloadRequest(source = "trigger") {
-    this.logger.info("Reload request received", { params: { source } });
-    this.lifecycleEvents.signalReload();
-    if (this.onReloadRequested) {
-      const broadcastFn = () => this.broadcastReload();
-      const result = this.onReloadRequested(broadcastFn);
+  async handleSignalRequest(descriptor, source) {
+    this.logger.info(descriptor.dispatchedLogLabel, { params: { source } });
+    descriptor.emitSignal();
+    if (descriptor.customCallback) {
+      const result = descriptor.customCallback(descriptor.broadcast);
       if (isPromise(result)) {
         await result;
       }
       return {
-        signal: "reload",
+        signal: descriptor.signal,
         results: [],
         timedOut: false,
         code: "ok"
       };
     }
-    return this.broadcastReload();
+    return descriptor.broadcast();
+  }
+  async handleReloadRequest(source = "trigger") {
+    return this.handleSignalRequest(
+      {
+        signal: "reload",
+        dispatchedLogLabel: "Reload dispatched",
+        emitSignal: () => this.lifecycleEvents.signalReload(),
+        customCallback: this.onReloadRequested,
+        broadcast: () => this.broadcastReload()
+      },
+      source
+    );
   }
-  /**
-   * Handle info request - calls custom callback or broadcasts to components.
-   *
-   * When called from signal handlers, the Promise executes but return values
-   * are not accessible due to Node.js signal handler constraints.
-   *
-   * @param source - Whether triggered from signal manager or manual trigger
-   */
   async handleInfoRequest(source = "trigger") {
-    this.logger.info("Info request received", { params: { source } });
-    this.lifecycleEvents.signalInfo();
-    if (this.onInfoRequested) {
-      const broadcastFn = () => this.broadcastInfo();
-      const result = this.onInfoRequested(broadcastFn);
-      if (isPromise(result)) {
-        await result;
-      }
-      return {
+    return this.handleSignalRequest(
+      {
         signal: "info",
-        results: [],
-        timedOut: false,
-        code: "ok"
-      };
-    }
-    return this.broadcastInfo();
+        dispatchedLogLabel: "Info dispatched",
+        emitSignal: () => this.lifecycleEvents.signalInfo(),
+        customCallback: this.onInfoRequested,
+        broadcast: () => this.broadcastInfo()
+      },
+      source
+    );
   }
-  /**
-   * Handle debug request - calls custom callback or broadcasts to components.
-   *
-   * When called from signal handlers, the Promise executes but return values
-   * are not accessible due to Node.js signal handler constraints.
-   *
-   * @param source - Whether triggered from signal manager or manual trigger
-   */
   async handleDebugRequest(source = "trigger") {
-    this.logger.info("Debug request received", { params: { source } });
-    this.lifecycleEvents.signalDebug();
-    if (this.onDebugRequested) {
-      const broadcastFn = () => this.broadcastDebug();
-      const result = this.onDebugRequested(broadcastFn);
-      if (isPromise(result)) {
-        await result;
-      }
-      return {
+    return this.handleSignalRequest(
+      {
         signal: "debug",
-        results: [],
-        timedOut: false,
-        code: "ok"
-      };
-    }
-    return this.broadcastDebug();
+        dispatchedLogLabel: "Debug dispatched",
+        emitSignal: () => this.lifecycleEvents.signalDebug(),
+        customCallback: this.onDebugRequested,
+        broadcast: () => this.broadcastDebug()
+      },
+      source
+    );
   }
   /**
-   * Broadcast reload signal to all running components.
-   * Calls onReload() on components that implement it.
-   * Continues on errors - collects all results.
+   * Shared signal broadcast pipeline used by reload/info/debug.
+   * Iterates running components, runs the picked handler with timeout, and
+   * aggregates per-component results into a SignalBroadcastResult.
    */
-  async broadcastReload() {
+  async runSignalBroadcast(descriptor) {
     const results = [];
-    const componentsToReload = this.components.filter(
+    const targets = this.components.filter(
       (component) => this.runningComponents.has(component.getName())
     );
     if (this.isStarting) {
-      this.logger.info(
-        "Reload during startup: only reloading already-started components"
-      );
+      this.logger.info(descriptor.startupLog);
     }
-    for (const component of componentsToReload) {
+    for (const component of targets) {
       const name = component.getName();
-      if (!component.onReload) {
+      const handler = descriptor.pickHandler(component);
+      if (!handler) {
         results.push({
           name,
           called: false,
@@ -5837,13 +6241,13 @@ var LifecycleManager = class extends EventEmitterProtected {
         });
         continue;
       }
-      this.lifecycleEvents.componentReloadStarted(name);
+      descriptor.emitStarted(name);
       const timeoutMS = component.signalTimeoutMS;
       let timeoutHandle;
       const timeoutResult = { timedOut: true };
       try {
-        const result = component.onReload();
-        const handlerPromise = isPromise(result) ? result : Promise.resolve(result);
+        const handlerResult = handler();
+        const handlerPromise = isPromise(handlerResult) ? handlerResult : Promise.resolve(handlerResult);
         const outcome = timeoutMS > 0 ? await Promise.race([
           handlerPromise,
           new Promise((resolve) => {
@@ -5853,7 +6257,7 @@ var LifecycleManager = class extends EventEmitterProtected {
           })
         ]) : await handlerPromise;
         if (outcome === timeoutResult) {
-          this.logger.entity(name).warn("Reload handler timed out", {
+          this.logger.entity(name).warn(descriptor.timeoutLog, {
             params: { timeoutMS }
           });
           Promise.resolve(handlerPromise).catch(() => {
@@ -5866,7 +6270,7 @@ var LifecycleManager = class extends EventEmitterProtected {
             code: "timeout"
           });
         } else {
-          this.lifecycleEvents.componentReloadCompleted(name);
+          descriptor.emitCompleted(name);
           results.push({
             name,
             called: true,
@@ -5877,10 +6281,10 @@ var LifecycleManager = class extends EventEmitterProtected {
         }
       } catch (error) {
         const err = error instanceof Error ? error : new Error(String(error));
-        this.logger.entity(name).error("Reload failed: {{error.message}}", {
+        this.logger.entity(name).error(descriptor.errorLog, {
           params: { error: err }
         });
-        this.lifecycleEvents.componentReloadFailed(name, err);
+        descriptor.emitFailed(name, err);
         results.push({
           name,
           called: true,
@@ -5901,108 +6305,45 @@ var LifecycleManager = class extends EventEmitterProtected {
     const isAllTimeout = calledResults.length > 0 && calledResults.every((result) => result.timedOut);
     const code = hasError ? isAllError ? "error" : "partial_error" : hasTimeout ? isAllTimeout ? "timeout" : "partial_timeout" : "ok";
     return {
-      signal: "reload",
+      signal: descriptor.signal,
       results,
       timedOut: hasTimeout,
       code
     };
   }
+  /**
+   * Broadcast reload signal to all running components.
+   * Calls onReload() on components that implement it.
+   * Continues on errors - collects all results.
+   */
+  async broadcastReload() {
+    return this.runSignalBroadcast({
+      signal: "reload",
+      pickHandler: (component) => component.onReload?.bind(component),
+      startupLog: "Reload during startup: only reloading already-started components",
+      timeoutLog: "Reload handler timed out",
+      errorLog: "Reload failed: {{error.message}}",
+      emitStarted: (name) => this.lifecycleEvents.componentReloadStarted(name),
+      emitCompleted: (name) => this.lifecycleEvents.componentReloadCompleted(name),
+      emitFailed: (name, error) => this.lifecycleEvents.componentReloadFailed(name, error)
+    });
+  }
   /**
    * Broadcast info signal to all running components.
    * Calls onInfo() on components that implement it.
    * Continues on errors - collects all results.
    */
   async broadcastInfo() {
-    const results = [];
-    const componentsToNotify = this.components.filter(
-      (component) => this.runningComponents.has(component.getName())
-    );
-    if (this.isStarting) {
-      this.logger.info(
-        "Info during startup: only notifying already-started components"
-      );
-    }
-    for (const component of componentsToNotify) {
-      const name = component.getName();
-      if (!component.onInfo) {
-        results.push({
-          name,
-          called: false,
-          error: null,
-          timedOut: false,
-          code: "no_handler"
-        });
-        continue;
-      }
-      this.lifecycleEvents.componentInfoStarted(name);
-      const timeoutMS = component.signalTimeoutMS;
-      let timeoutHandle;
-      const timeoutResult = { timedOut: true };
-      try {
-        const result = component.onInfo();
-        const handlerPromise = isPromise(result) ? result : Promise.resolve(result);
-        const outcome = timeoutMS > 0 ? await Promise.race([
-          handlerPromise,
-          new Promise((resolve) => {
-            timeoutHandle = setTimeout(() => {
-              resolve(timeoutResult);
-            }, timeoutMS);
-          })
-        ]) : await handlerPromise;
-        if (outcome === timeoutResult) {
-          this.logger.entity(name).warn("Info handler timed out", {
-            params: { timeoutMS }
-          });
-          Promise.resolve(handlerPromise).catch(() => {
-          });
-          results.push({
-            name,
-            called: true,
-            error: null,
-            timedOut: true,
-            code: "timeout"
-          });
-        } else {
-          this.lifecycleEvents.componentInfoCompleted(name);
-          results.push({
-            name,
-            called: true,
-            error: null,
-            timedOut: false,
-            code: "called"
-          });
-        }
-      } catch (error) {
-        const err = error instanceof Error ? error : new Error(String(error));
-        this.logger.entity(name).error("Info handler failed: {{error.message}}", {
-          params: { error: err }
-        });
-        this.lifecycleEvents.componentInfoFailed(name, err);
-        results.push({
-          name,
-          called: true,
-          error: err,
-          timedOut: false,
-          code: "error"
-        });
-      } finally {
-        if (timeoutHandle) {
-          clearTimeout(timeoutHandle);
-        }
-      }
-    }
-    const calledResults = results.filter((result) => result.called);
-    const hasError = calledResults.some((result) => result.error);
-    const isAllError = calledResults.length > 0 && calledResults.every((result) => result.error);
-    const hasTimeout = calledResults.some((result) => result.timedOut);
-    const isAllTimeout = calledResults.length > 0 && calledResults.every((result) => result.timedOut);
-    const code = hasError ? isAllError ? "error" : "partial_error" : hasTimeout ? isAllTimeout ? "timeout" : "partial_timeout" : "ok";
-    return {
+    return this.runSignalBroadcast({
       signal: "info",
-      results,
-      timedOut: hasTimeout,
-      code
-    };
+      pickHandler: (component) => component.onInfo?.bind(component),
+      startupLog: "Info during startup: only notifying already-started components",
+      timeoutLog: "Info handler timed out",
+      errorLog: "Info handler failed: {{error.message}}",
+      emitStarted: (name) => this.lifecycleEvents.componentInfoStarted(name),
+      emitCompleted: (name) => this.lifecycleEvents.componentInfoCompleted(name),
+      emitFailed: (name, error) => this.lifecycleEvents.componentInfoFailed(name, error)
+    });
   }
   /**
    * Broadcast debug signal to all running components.
@@ -6010,96 +6351,16 @@ var LifecycleManager = class extends EventEmitterProtected {
    * Continues on errors - collects all results.
    */
   async broadcastDebug() {
-    const results = [];
-    const componentsToNotify = this.components.filter(
-      (component) => this.runningComponents.has(component.getName())
-    );
-    if (this.isStarting) {
-      this.logger.info(
-        "Debug during startup: only notifying already-started components"
-      );
-    }
-    for (const component of componentsToNotify) {
-      const name = component.getName();
-      if (!component.onDebug) {
-        results.push({
-          name,
-          called: false,
-          error: null,
-          timedOut: false,
-          code: "no_handler"
-        });
-        continue;
-      }
-      this.lifecycleEvents.componentDebugStarted(name);
-      const timeoutMS = component.signalTimeoutMS;
-      let timeoutHandle;
-      const timeoutResult = { timedOut: true };
-      try {
-        const result = component.onDebug();
-        const handlerPromise = isPromise(result) ? result : Promise.resolve(result);
-        const outcome = timeoutMS > 0 ? await Promise.race([
-          handlerPromise,
-          new Promise((resolve) => {
-            timeoutHandle = setTimeout(() => {
-              resolve(timeoutResult);
-            }, timeoutMS);
-          })
-        ]) : await handlerPromise;
-        if (outcome === timeoutResult) {
-          this.logger.entity(name).warn("Debug handler timed out", {
-            params: { timeoutMS }
-          });
-          Promise.resolve(handlerPromise).catch(() => {
-          });
-          results.push({
-            name,
-            called: true,
-            error: null,
-            timedOut: true,
-            code: "timeout"
-          });
-        } else {
-          this.lifecycleEvents.componentDebugCompleted(name);
-          results.push({
-            name,
-            called: true,
-            error: null,
-            timedOut: false,
-            code: "called"
-          });
-        }
-      } catch (error) {
-        const err = error instanceof Error ? error : new Error(String(error));
-        this.logger.entity(name).error("Debug handler failed: {{error.message}}", {
-          params: { error: err }
-        });
-        this.lifecycleEvents.componentDebugFailed(name, err);
-        results.push({
-          name,
-          called: true,
-          error: err,
-          timedOut: false,
-          code: "error"
-        });
-      } finally {
-        if (timeoutHandle) {
-          clearTimeout(timeoutHandle);
-        }
-      }
-    }
-    const calledResults = results.filter((result) => result.called);
-    const hasError = calledResults.some((result) => result.error);
-    const isAllError = calledResults.length > 0 && calledResults.every((result) => result.error);
-    const hasTimeout = calledResults.some((result) => result.timedOut);
-    const isAllTimeout = calledResults.length > 0 && calledResults.every((result) => result.timedOut);
-    const code = hasError ? isAllError ? "error" : "partial_error" : hasTimeout ? isAllTimeout ? "timeout" : "partial_timeout" : "ok";
-    return {
+    return this.runSignalBroadcast({
       signal: "debug",
-      results,
-      timedOut: hasTimeout,
-      code
-    };
+      pickHandler: (component) => component.onDebug?.bind(component),
+      startupLog: "Debug during startup: only notifying already-started components",
+      timeoutLog: "Debug handler timed out",
+      errorLog: "Debug handler failed: {{error.message}}",
+      emitStarted: (name) => this.lifecycleEvents.componentDebugStarted(name),
+      emitCompleted: (name) => this.lifecycleEvents.componentDebugCompleted(name),
+      emitFailed: (name, error) => this.lifecycleEvents.componentDebugFailed(name, error)
+    });
   }
 };
 
@@ -6125,6 +6386,10 @@ var BaseComponent = class {
   name;
   /** Reference to component-scoped lifecycle (set by manager when registered) */
   lifecycle;
+  /** @internal Set by LifecycleManager while the component is running. */
+  _unexpectedStopHandler;
+  /** @internal Incremented whenever the unexpected-stop handler is re-armed or cleared. */
+  _unexpectedStopGeneration = 0;
   /**
    * Create a new component
    *
@@ -6159,6 +6424,24 @@ var BaseComponent = class {
       // Default if undefined/null/non-finite
     );
   }
+  /** @internal Called by LifecycleManager after a successful start. */
+  _setUnexpectedStopHandler(handler) {
+    this._unexpectedStopGeneration += 1;
+    this._unexpectedStopHandler = handler;
+    const generation = this._unexpectedStopGeneration;
+    this.reportUnexpectedStop = (error) => {
+      if (this._unexpectedStopGeneration !== generation) {
+        return false;
+      }
+      return this._unexpectedStopHandler?.(error) ?? false;
+    };
+  }
+  /** @internal Called by LifecycleManager when stop begins or component is unregistered. */
+  _clearUnexpectedStopHandler() {
+    this._unexpectedStopGeneration += 1;
+    this._unexpectedStopHandler = void 0;
+    this.reportUnexpectedStop = () => false;
+  }
   /**
    * Get component name
    */
@@ -6177,6 +6460,38 @@ var BaseComponent = class {
   isOptional() {
     return this.optional;
   }
+  /**
+   * Run-scoped unexpected-stop callback. Rebound by LifecycleManager on each
+   * successful start so captured references from older runs go stale.
+   */
+  reportUnexpectedStop = () => false;
+  /**
+   * Get this component's own status from the manager's perspective.
+   *
+   * Equivalent to `this.lifecycle.getComponentStatus(this.getName())` but without
+   * needing to pass the name. Returns `undefined` if the component is not registered.
+   *
+   * Check `status?.state === 'running'` to test whether the component is currently running.
+   */
+  getSelfStatus() {
+    return this.lifecycle?.getComponentStatus(this.name);
+  }
+  /**
+   * Capture a run-scoped unexpected-stop reporter for async listeners created during start().
+   *
+   * Unlike calling `this.reportUnexpectedStop()` later, the returned callback becomes a no-op
+   * once the component is stopped, unregistered, or restarted. This prevents stale listeners
+   * from a previous run from stopping a newer run of the same component instance.
+   */
+  getUnexpectedStopReporter() {
+    const generation = this._unexpectedStopGeneration;
+    return (error) => {
+      if (this._unexpectedStopGeneration !== generation) {
+        return false;
+      }
+      return this._unexpectedStopHandler?.(error) ?? false;
+    };
+  }
 };
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {