lifecycleion 0.0.12 → 0.0.14

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

@@ -956,6 +956,9 @@ var ComponentLifecycle = class {
   getSignalStatus() {
     return this.manager.getSignalStatus();
   }
+  getShutdownEscalationStatus() {
+    return this.manager.getShutdownEscalationStatus();
+  }
   triggerReload() {
     return this.manager.triggerReload();
   }
@@ -1134,6 +1137,15 @@ var LifecycleManagerEvents = class {
   lifecycleManagerShutdownCompleted(input) {
     this.emit("lifecycle-manager:shutdown-completed", input);
   }
+  lifecycleManagerShutdownEscalationArmed(input) {
+    this.emit("lifecycle-manager:shutdown-escalation-armed", input);
+  }
+  lifecycleManagerShutdownEscalationExpired(input) {
+    this.emit("lifecycle-manager:shutdown-escalation-expired", input);
+  }
+  lifecycleManagerShutdownEscalationForced(input) {
+    this.emit("lifecycle-manager:shutdown-escalation-forced", input);
+  }
   componentStarting(name) {
     this.emit("component:starting", { name });
   }
@@ -1201,6 +1213,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 });
   }
@@ -1210,8 +1232,8 @@ var LifecycleManagerEvents = class {
   componentStartupRollback(name) {
     this.emit("component:startup-rollback", { name });
   }
-  signalShutdown(method) {
-    this.emit("signal:shutdown", { method });
+  signalShutdown(method, isAlreadyShuttingDown = false) {
+    this.emit("signal:shutdown", { method, isAlreadyShuttingDown });
   }
   signalReload() {
     this.emit("signal:reload", void 0);
@@ -1387,6 +1409,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
 import { ulid } from "ulid";
 import readline from "readline";
@@ -1921,6 +1962,7 @@ var LifecycleManager = class extends EventEmitterProtected {
   attachSignalsBeforeStartup;
   attachSignalsOnStart;
   detachSignalsOnStop;
+  repeatedShutdownRequestPolicy;
   // Component management
   components = [];
   runningComponents = /* @__PURE__ */ new Set();
@@ -1930,8 +1972,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().
@@ -1940,6 +1989,17 @@ var LifecycleManager = class extends EventEmitterProtected {
   pendingLoggerExitResolve = null;
   shutdownMethod = null;
   lastShutdownResult = null;
+  repeatedShutdownExpiryTimer = null;
+  repeatedShutdownRequestState = {
+    requestCount: 0,
+    firstMethod: null,
+    latestMethod: null,
+    firstRequestAt: null,
+    latestRequestAt: null,
+    repeatedWindowStartedAt: null,
+    hasTriggeredForceShutdown: false,
+    remainsArmedUntil: null
+  };
   // Signal management
   processSignalManager = null;
   onReloadRequested;
@@ -1966,6 +2026,37 @@ var LifecycleManager = class extends EventEmitterProtected {
     this.attachSignalsBeforeStartup = options.attachSignalsBeforeStartup ?? false;
     this.attachSignalsOnStart = options.attachSignalsOnStart ?? false;
     this.detachSignalsOnStop = options.detachSignalsOnStop ?? false;
+    const repeatedShutdownRequestPolicy = options.repeatedShutdownRequestPolicy;
+    if (repeatedShutdownRequestPolicy === void 0) {
+      this.repeatedShutdownRequestPolicy = void 0;
+    } else {
+      const hasFiniteExplicitArmedAfterFailureMS = Number.isFinite(
+        repeatedShutdownRequestPolicy.armedAfterFailureMS
+      );
+      const forceAfterCount = finiteClampMin(
+        repeatedShutdownRequestPolicy.forceAfterCount,
+        1,
+        3
+      );
+      const withinMS = finiteClampMin(
+        repeatedShutdownRequestPolicy.withinMS,
+        0,
+        2e3
+      );
+      const armedAfterFailureMS = finiteClampMin(
+        repeatedShutdownRequestPolicy.armedAfterFailureMS,
+        0,
+        withinMS * forceAfterCount
+      );
+      this.repeatedShutdownRequestPolicy = {
+        forceAfterCount,
+        withinMS,
+        armedAfterFailureMS,
+        countManualRetriesTowardEscalation: repeatedShutdownRequestPolicy.countManualRetriesTowardEscalation ?? false,
+        hasExplicitArmedAfterFailureMS: hasFiniteExplicitArmedAfterFailureMS,
+        onForceShutdown: repeatedShutdownRequestPolicy.onForceShutdown
+      };
+    }
     this.onReloadRequested = options.onReloadRequested;
     this.onInfoRequested = options.onInfoRequested;
     this.onDebugRequested = options.onDebugRequested;
@@ -2038,7 +2129,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
@@ -2047,7 +2138,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)
@@ -2055,11 +2146,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
@@ -2072,7 +2163,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,
@@ -2124,10 +2215,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();
@@ -2474,7 +2568,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
       };
@@ -2534,6 +2628,9 @@ var LifecycleManager = class extends EventEmitterProtected {
       };
     }
     this.isStarting = true;
+    this.autoAttachedSignalsDuringStartup = false;
+    this.unexpectedStopsDuringStartup.clear();
+    this.resetRepeatedShutdownRequestState();
     this.shutdownMethod = null;
     this.lastShutdownResult = null;
     const didAutoAttachSignalsForBulkStartup = this.attachSignalsBeforeStartup ? this.autoAttachSignals("bulk startup") : false;
@@ -2665,13 +2762,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
+                  )
                 }
               }
             );
@@ -2685,14 +2818,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
+                  )
                 }
               }
             );
@@ -2709,6 +2846,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;
@@ -2732,6 +2888,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),
@@ -2763,10 +2938,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();
     }
   }
   /**
@@ -2830,7 +3007,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"
       };
     }
@@ -2841,7 +3018,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"
       };
     }
@@ -2875,7 +3052,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"
       };
     }
@@ -2974,6 +3151,51 @@ var LifecycleManager = class extends EventEmitterProtected {
       shutdownMethod: this.shutdownMethod
     };
   }
+  /**
+   * Get status information about repeated shutdown escalation configuration and runtime state.
+   */
+  getShutdownEscalationStatus() {
+    if (this.repeatedShutdownRequestPolicy === void 0) {
+      return {
+        configured: false,
+        isShuttingDown: this.isShuttingDown,
+        isArmed: false,
+        forceAfterCount: null,
+        withinMS: null,
+        armedAfterFailureMS: null,
+        armedAfterFailureMSSource: null,
+        requestCount: 0,
+        firstMethod: null,
+        latestMethod: null,
+        firstRequestAt: null,
+        latestRequestAt: null,
+        repeatedWindowStartedAt: null,
+        armedUntil: null,
+        hasTriggeredForceShutdown: false
+      };
+    }
+    this.normalizeRepeatedShutdownRequestStateArmedStatus();
+    const armedUntil = this.repeatedShutdownRequestState.remainsArmedUntil;
+    const isArmed = armedUntil !== null;
+    return {
+      configured: true,
+      isShuttingDown: this.isShuttingDown,
+      isArmed,
+      forceAfterCount: this.repeatedShutdownRequestPolicy.forceAfterCount,
+      withinMS: this.repeatedShutdownRequestPolicy.withinMS,
+      armedAfterFailureMS: this.repeatedShutdownRequestPolicy.armedAfterFailureMS,
+      armedAfterFailureMSSource: this.repeatedShutdownRequestPolicy.hasExplicitArmedAfterFailureMS ? "explicit" : "derived",
+      countManualRetriesTowardEscalation: this.repeatedShutdownRequestPolicy.countManualRetriesTowardEscalation,
+      requestCount: this.repeatedShutdownRequestState.requestCount,
+      firstMethod: this.repeatedShutdownRequestState.firstMethod,
+      latestMethod: this.repeatedShutdownRequestState.latestMethod,
+      firstRequestAt: this.repeatedShutdownRequestState.firstRequestAt,
+      latestRequestAt: this.repeatedShutdownRequestState.latestRequestAt,
+      repeatedWindowStartedAt: this.repeatedShutdownRequestState.repeatedWindowStartedAt,
+      armedUntil: isArmed ? armedUntil : null,
+      hasTriggeredForceShutdown: this.repeatedShutdownRequestState.hasTriggeredForceShutdown
+    };
+  }
   /**
    * Enable Logger exit hook integration
    *
@@ -3012,7 +3234,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 }
               }
@@ -3021,7 +3243,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" };
@@ -3111,7 +3333,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,
@@ -3124,7 +3346,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,
@@ -3340,7 +3562,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, {
@@ -3400,7 +3622,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, {
@@ -3673,7 +3895,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,
@@ -3685,7 +3907,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
         });
       }
@@ -3696,7 +3918,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,
@@ -3708,7 +3930,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
         });
       }
@@ -3717,7 +3939,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,
@@ -3729,7 +3951,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
         });
       }
@@ -3999,9 +4221,26 @@ var LifecycleManager = class extends EventEmitterProtected {
         code: "already_in_progress"
       };
     }
+    this.normalizeRepeatedShutdownRequestStateArmedStatus();
+    const repeatedShutdownPolicy = this.repeatedShutdownRequestPolicy;
+    const isManualRetryWhileArmed = repeatedShutdownPolicy !== void 0 && method === "manual" && this.repeatedShutdownRequestState.firstRequestAt !== null && this.repeatedShutdownRequestState.remainsArmedUntil !== null;
+    if (isManualRetryWhileArmed) {
+      if (repeatedShutdownPolicy.countManualRetriesTowardEscalation) {
+        this.handleRepeatedShutdownRequest(method);
+      } else {
+        this.resetRepeatedShutdownRequestState();
+      }
+    }
+    if (this.repeatedShutdownRequestState.remainsArmedUntil !== null) {
+      this.clearRepeatedShutdownExpiryTimer();
+      this.repeatedShutdownRequestState.remainsArmedUntil = null;
+    }
     this.isShuttingDown = true;
     this.shutdownToken = ulid2();
     this.shutdownMethod = method;
+    if (this.repeatedShutdownRequestPolicy && this.repeatedShutdownRequestState.firstRequestAt === null) {
+      this.seedRepeatedShutdownRequestState(method);
+    }
     const isDuringStartup = this.isStarting;
     this.logger.info("Stopping all components", { params: { method } });
     this.lifecycleEvents.lifecycleManagerShutdownInitiated(
@@ -4026,8 +4265,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 {
@@ -4058,34 +4296,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)",
@@ -4101,18 +4342,40 @@ 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) {
+          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"]("Shutdown completed", {
-        params: {
-          stopped: stoppedComponents.length,
-          stalled: stalledComponents.length,
-          durationMS
+      this.logger[isSuccess ? "success" : "warn"](
+        isSuccess ? "Shutdown completed successfully" : "Shutdown attempt completed with stalled components or timeout",
+        {
+          params: {
+            stopped: stoppedComponents.size,
+            stalled: stalledComponents.length,
+            durationMS
+          }
         }
-      });
+      );
       const result = {
         success: isSuccess,
-        stoppedComponents,
+        stoppedComponents: Array.from(stoppedComponents),
         stalledComponents,
         durationMS,
         timedOut: hasTimedOut || void 0,
@@ -4127,6 +4390,11 @@ var LifecycleManager = class extends EventEmitterProtected {
         method,
         duringStartup: isDuringStartup
       });
+      if (isSuccess) {
+        this.resetRepeatedShutdownRequestState();
+      } else {
+        this.armRepeatedShutdownAfterFailure();
+      }
       return result;
     } finally {
       if (timeoutHandle) {
@@ -4158,7 +4426,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"
       };
     }
@@ -4169,12 +4437,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,
@@ -4194,7 +4465,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"
       };
     }
@@ -4206,7 +4477,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"
       };
     }
@@ -4216,7 +4487,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"
       };
     }
@@ -4225,7 +4496,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)
       };
@@ -4289,6 +4560,9 @@ var LifecycleManager = class extends EventEmitterProtected {
     const timeoutMS = component.startupTimeoutMS;
     const startAttemptToken = ulid2();
     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;
@@ -4331,6 +4605,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);
@@ -4358,6 +4644,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");
@@ -4377,9 +4666,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 }
@@ -4424,7 +4728,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"
       };
     }
@@ -4432,7 +4736,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)
       };
@@ -4441,7 +4745,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)
       };
@@ -4457,6 +4761,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,
@@ -4593,9 +4901,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 {
@@ -4616,7 +4926,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({
@@ -4635,9 +4954,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) ?? {
@@ -4660,15 +4977,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)
@@ -4711,8 +5028,6 @@ var LifecycleManager = class extends EventEmitterProtected {
         gracefulTimedOut: context.gracefulTimedOut
       }
     });
-    const timeoutMS = component.shutdownForceTimeoutMS;
-    let timeoutHandle;
     if (!component.onShutdownForce) {
       const stallInfo = {
         name,
@@ -4746,6 +5061,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) {
@@ -4764,23 +5082,44 @@ var LifecycleManager = class extends EventEmitterProtected {
                 );
               }
             }
-            Promise.resolve(forcePromise).catch(() => {
+            const forceAttemptToken = this.componentStopAttemptTokens.get(name) ?? ulid2();
+            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) ?? {
@@ -4801,8 +5140,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",
@@ -4833,12 +5179,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);
       }
@@ -4915,7 +5262,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
+              )
             }
           }
         );
@@ -4929,10 +5278,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}`);
@@ -4974,6 +5326,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 = ulid2();
+    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
    */
@@ -5255,121 +5811,377 @@ var LifecycleManager = class extends EventEmitterProtected {
   }
   /**
    * Handle shutdown signal - initiates stopAllComponents().
-   * Double signal protection: if already shutting down, log warning and ignore.
+   *
+   * Four cases depending on the current shutdown state:
+   *
+   * 1. **Active shutdown** (`isShuttingDown = true`): escalate through the
+   *    repeated-shutdown policy if configured, otherwise log and discard.
+   *    Emits `signal:shutdown` with `isAlreadyShuttingDown: true` and returns
+   *    without starting another shutdown.
+   *
+   * 2. **Armed post-failure** (previous shutdown finished, armed window still
+   *    open): count the request toward the escalation window, emit
+   *    `signal:shutdown` with `isAlreadyShuttingDown: false`, then start a
+   *    new `stopAllComponents()` run to retry.
+   *
+   * 3. **Armed post-failure expired** (armed window opened but has since
+   *    elapsed): expire the stale state, treat the request as a fresh
+   *    shutdown (falls through to case 4).
+   *
+   * 4. **Fresh shutdown** (no prior shutdown state): seed escalation tracking
+   *    if policy is configured, emit `signal:shutdown` with
+   *    `isAlreadyShuttingDown: false`, and start `stopAllComponents()`.
+   *
+   * In all cases `signal:shutdown` is emitted exactly once.
    */
   handleShutdownRequest(method) {
     if (this.isShuttingDown) {
-      this.logger.warn("Shutdown already in progress, ignoring signal", {
-        params: { method }
-      });
-      return;
+      this.lifecycleEvents.signalShutdown(method, true);
+      if (this.handleRepeatedShutdownRequest(method)) {
+        return;
+      }
+    }
+    let didEmitShutdownSignal = false;
+    let shouldSeedRepeatedShutdownState = this.repeatedShutdownRequestPolicy !== void 0;
+    if (this.repeatedShutdownRequestPolicy && this.repeatedShutdownRequestState.firstRequestAt !== null && this.normalizeRepeatedShutdownRequestStateArmedStatus()) {
+      this.lifecycleEvents.signalShutdown(method, false);
+      didEmitShutdownSignal = true;
+      shouldSeedRepeatedShutdownState = false;
+      this.handleRepeatedShutdownRequest(method);
+    }
+    if (shouldSeedRepeatedShutdownState) {
+      this.seedRepeatedShutdownRequestState(method);
     }
     this.logger.info("Shutdown signal received", { params: { method } });
-    this.lifecycleEvents.signalShutdown(method);
+    if (!didEmitShutdownSignal) {
+      this.lifecycleEvents.signalShutdown(method, false);
+    }
     void this.stopAllComponentsInternal(method, {
       ...this.shutdownOptions
     });
   }
   /**
-   * Handle reload request - calls custom callback or broadcasts to components.
-   *
-   * 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.
-   *
-   * When called from manual triggers (source='trigger'), the Promise is awaited
-   * and results are returned for programmatic use.
+   * Tracks repeated shutdown requests during an active shutdown and optionally
+   * invokes the configured force shutdown callback when the threshold is reached.
    *
-   * @param source - Whether triggered from signal manager or manual trigger
+   * @returns true when the request was consumed as part of the repeated-shutdown
+   * escalation flow, false when the caller should treat it as a fresh shutdown request
    */
-  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);
-      if (isPromise(result)) {
-        await result;
-      }
-      return {
-        signal: "reload",
-        results: [],
-        timedOut: false,
-        code: "ok"
-      };
+  handleRepeatedShutdownRequest(method) {
+    const policy = this.repeatedShutdownRequestPolicy;
+    if (!policy) {
+      this.logger.warn("Shutdown already in progress, ignoring signal", {
+        params: { method }
+      });
+      return true;
     }
-    return this.broadcastReload();
+    const now = Date.now();
+    const state = this.repeatedShutdownRequestState;
+    if (state.remainsArmedUntil !== null) {
+      if (now >= state.remainsArmedUntil) {
+        this.expireRepeatedShutdownRequestState();
+        return false;
+      }
+      this.refreshRepeatedShutdownArmedWindow(now);
+    }
+    const shouldStartNewWindow = state.repeatedWindowStartedAt === null || now - state.repeatedWindowStartedAt > policy.withinMS;
+    if (shouldStartNewWindow) {
+      state.requestCount = 1;
+      state.repeatedWindowStartedAt = now;
+    } else {
+      state.requestCount++;
+    }
+    state.latestMethod = method;
+    state.latestRequestAt = now;
+    this.logger.warn(
+      this.isShuttingDown ? "Shutdown already in progress, tracking repeated signal" : "Previous shutdown attempt finished with stalled components or timeout, escalation window still armed, tracking repeated request",
+      {
+        params: {
+          method,
+          requestCount: state.requestCount,
+          firstMethod: state.firstMethod,
+          latestMethod: state.latestMethod,
+          firstRequestAt: state.firstRequestAt,
+          latestRequestAt: state.latestRequestAt,
+          repeatedWindowStartedAt: state.repeatedWindowStartedAt,
+          remainsArmedUntil: state.remainsArmedUntil,
+          withinMS: policy.withinMS,
+          forceAfterCount: policy.forceAfterCount
+        }
+      }
+    );
+    if (
+      // Force escalation is single-fire per shutdown cycle. Later requests are
+      // still logged but do not re-enter user force-shutdown logic.
+      state.hasTriggeredForceShutdown || state.requestCount < policy.forceAfterCount || state.firstMethod === null || state.firstRequestAt === null || state.latestMethod === null || state.latestRequestAt === null
+    ) {
+      return true;
+    }
+    state.hasTriggeredForceShutdown = true;
+    const context = {
+      requestCount: state.requestCount,
+      firstMethod: state.firstMethod,
+      latestMethod: state.latestMethod,
+      firstRequestAt: state.firstRequestAt,
+      latestRequestAt: state.latestRequestAt,
+      isShuttingDown: this.isShuttingDown,
+      wasArmedAfterFailure: state.remainsArmedUntil !== null
+    };
+    this.logger.warn(
+      "Repeated shutdown request threshold reached, invoking force shutdown handler",
+      {
+        params: {
+          method,
+          requestCount: context.requestCount,
+          firstMethod: context.firstMethod,
+          latestMethod: context.latestMethod,
+          firstRequestAt: context.firstRequestAt,
+          latestRequestAt: context.latestRequestAt,
+          repeatedWindowStartedAt: state.repeatedWindowStartedAt,
+          remainsArmedUntil: state.remainsArmedUntil,
+          withinMS: policy.withinMS,
+          forceAfterCount: policy.forceAfterCount
+        }
+      }
+    );
+    safeHandleCallback(
+      "repeatedShutdownRequestPolicy.onForceShutdown",
+      policy.onForceShutdown,
+      context
+    );
+    this.lifecycleEvents.lifecycleManagerShutdownEscalationForced({
+      firstMethod: context.firstMethod,
+      latestMethod: context.latestMethod,
+      requestCount: context.requestCount,
+      firstRequestAt: context.firstRequestAt,
+      latestRequestAt: context.latestRequestAt,
+      wasArmedAfterFailure: context.wasArmedAfterFailure
+    });
+    return true;
   }
   /**
-   * 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.
+   * Clears repeated shutdown request tracking so a new shutdown cycle starts fresh.
+   */
+  resetRepeatedShutdownRequestState() {
+    this.clearRepeatedShutdownExpiryTimer();
+    this.repeatedShutdownRequestState = {
+      requestCount: 0,
+      firstMethod: null,
+      latestMethod: null,
+      firstRequestAt: null,
+      latestRequestAt: null,
+      repeatedWindowStartedAt: null,
+      hasTriggeredForceShutdown: false,
+      remainsArmedUntil: null
+    };
+  }
+  /**
+   * Clear any pending expiration timer for the post-failure escalation window.
+   */
+  clearRepeatedShutdownExpiryTimer() {
+    if (this.repeatedShutdownExpiryTimer === null) {
+      return;
+    }
+    clearTimeout(this.repeatedShutdownExpiryTimer);
+    this.repeatedShutdownExpiryTimer = null;
+  }
+  /**
+   * Returns whether post-failure escalation remains armed after first
+   * normalizing any stale timer-backed state.
    *
-   * @param source - Whether triggered from signal manager or manual trigger
+   * The method can expire old armed windows as a side effect because the timer
+   * callback may not have run yet on a delayed event loop. Callers use this
+   * when they need the effective runtime truth, not just the last timer write.
    */
-  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;
+  normalizeRepeatedShutdownRequestStateArmedStatus(now = Date.now()) {
+    const armedUntil = this.repeatedShutdownRequestState.remainsArmedUntil;
+    if (armedUntil === null) {
+      return false;
+    }
+    if (now >= armedUntil) {
+      this.expireRepeatedShutdownRequestState();
+      return false;
+    }
+    return true;
+  }
+  /**
+   * Transition armed post-failure escalation state into its expired/reset state.
+   */
+  expireRepeatedShutdownRequestState() {
+    const policy = this.repeatedShutdownRequestPolicy;
+    const state = this.repeatedShutdownRequestState;
+    if (!policy || state.remainsArmedUntil === null) {
+      return;
+    }
+    const armedUntil = state.remainsArmedUntil;
+    this.clearRepeatedShutdownExpiryTimer();
+    const expiredState = {
+      firstMethod: state.firstMethod,
+      latestMethod: state.latestMethod,
+      requestCount: state.requestCount,
+      armedUntil
+    };
+    this.logger.warn(
+      "Repeated shutdown escalation window expired, clearing previous shutdown state",
+      {
+        params: {
+          remainsArmedUntil: armedUntil,
+          withinMS: policy.withinMS,
+          forceAfterCount: policy.forceAfterCount
+        }
       }
-      return {
-        signal: "info",
-        results: [],
-        timedOut: false,
-        code: "ok"
-      };
+    );
+    if (expiredState.firstMethod !== null) {
+      this.lifecycleEvents.lifecycleManagerShutdownEscalationExpired({
+        firstMethod: expiredState.firstMethod,
+        latestMethod: expiredState.latestMethod,
+        requestCount: expiredState.requestCount,
+        armedUntil: expiredState.armedUntil
+      });
     }
-    return this.broadcastInfo();
+    this.resetRepeatedShutdownRequestState();
   }
   /**
-   * Handle debug request - calls custom callback or broadcasts to components.
+   * Arms or refreshes the post-failure escalation window and its expiration timer.
+   */
+  refreshRepeatedShutdownArmedWindow(now = Date.now()) {
+    const policy = this.repeatedShutdownRequestPolicy;
+    if (!policy) {
+      return;
+    }
+    this.clearRepeatedShutdownExpiryTimer();
+    const armedUntil = now + policy.armedAfterFailureMS;
+    this.repeatedShutdownRequestState.remainsArmedUntil = armedUntil;
+    this.repeatedShutdownExpiryTimer = setTimeout(() => {
+      this.expireRepeatedShutdownRequestState();
+    }, policy.armedAfterFailureMS);
+    this.repeatedShutdownExpiryTimer.unref();
+  }
+  /**
+   * Seeds shutdown escalation tracking for a new shutdown cycle.
    *
-   * When called from signal handlers, the Promise executes but return values
-   * are not accessible due to Node.js signal handler constraints.
+   * The first shutdown trigger starts graceful shutdown and arms escalation with
+   * an effective post-start count of 0. Later shutdown requests can then count
+   * toward the configured force threshold regardless of whether the shutdown
+   * started from a signal, keyboard shortcut, or direct API call.
+   */
+  seedRepeatedShutdownRequestState(method) {
+    const now = Date.now();
+    this.repeatedShutdownRequestState = {
+      requestCount: 0,
+      firstMethod: method,
+      latestMethod: method,
+      firstRequestAt: now,
+      latestRequestAt: now,
+      repeatedWindowStartedAt: null,
+      hasTriggeredForceShutdown: false,
+      remainsArmedUntil: null
+    };
+  }
+  /**
+   * Preserves a short-lived post-failure escalation window after shutdown
+   * returns unsuccessfully so operators can keep pressing shutdown without
+   * losing the existing force count the moment the graceful attempt finishes.
+   */
+  armRepeatedShutdownAfterFailure() {
+    const policy = this.repeatedShutdownRequestPolicy;
+    const state = this.repeatedShutdownRequestState;
+    if (!policy || policy.armedAfterFailureMS <= 0 || // armedAfterFailureMS = 0 disables post-failure arming
+    state.firstRequestAt === null || state.hasTriggeredForceShutdown) {
+      return;
+    }
+    this.refreshRepeatedShutdownArmedWindow();
+    const armedUntil = state.remainsArmedUntil;
+    if (state.firstMethod !== null && armedUntil !== null) {
+      this.lifecycleEvents.lifecycleManagerShutdownEscalationArmed({
+        firstMethod: state.firstMethod,
+        requestCount: state.requestCount,
+        armedUntil
+      });
+    }
+  }
+  /**
+   * 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.
    *
-   * @param source - Whether triggered from signal manager or manual trigger
+   * When called from signal handlers (source='signal'), the Promise is started
+   * 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.
    */
-  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);
+  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: "debug",
+        signal: descriptor.signal,
         results: [],
         timedOut: false,
         code: "ok"
       };
     }
-    return this.broadcastDebug();
+    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
+    );
+  }
+  async handleInfoRequest(source = "trigger") {
+    return this.handleSignalRequest(
+      {
+        signal: "info",
+        dispatchedLogLabel: "Info dispatched",
+        emitSignal: () => this.lifecycleEvents.signalInfo(),
+        customCallback: this.onInfoRequested,
+        broadcast: () => this.broadcastInfo()
+      },
+      source
+    );
+  }
+  async handleDebugRequest(source = "trigger") {
+    return this.handleSignalRequest(
+      {
+        signal: "debug",
+        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,
@@ -5379,13 +6191,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) => {
@@ -5395,7 +6207,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(() => {
@@ -5408,7 +6220,7 @@ var LifecycleManager = class extends EventEmitterProtected {
             code: "timeout"
           });
         } else {
-          this.lifecycleEvents.componentReloadCompleted(name);
+          descriptor.emitCompleted(name);
           results.push({
             name,
             called: true,
@@ -5419,10 +6231,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,
@@ -5443,108 +6255,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.
@@ -5552,96 +6301,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)
+    });
   }
 };
 
@@ -5667,6 +6336,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
    *
@@ -5701,6 +6374,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
    */
@@ -5719,6 +6410,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;
+    };
+  }
 };
 export {
   BaseComponent,