lifecycleion 0.0.13 → 0.0.15

package/dist/lib/lifecycle-manager/index.d.cts

@@ -158,7 +158,7 @@ interface RestartComponentOptions {
 /**
  * Stable, machine-readable failure codes for individual component operations
  */
-type ComponentOperationFailureCode = 'component_not_found' | 'component_already_running' | 'component_already_starting' | 'component_already_stopping' | 'component_not_running' | 'component_stalled' | 'missing_dependency' | 'dependency_not_running' | 'has_running_dependents' | 'startup_in_progress' | 'shutdown_in_progress' | 'component_startup_timeout' | 'component_shutdown_timeout' | 'restart_stop_failed' | 'restart_start_failed' | 'unknown_error';
+type ComponentOperationFailureCode = 'component_not_found' | 'component_already_running' | 'component_already_starting' | 'component_already_stopping' | 'component_not_running' | 'component_stalled' | 'missing_dependency' | 'dependency_not_running' | 'has_running_dependents' | 'startup_in_progress' | 'shutdown_in_progress' | 'component_unexpected_stop' | 'component_startup_timeout' | 'component_shutdown_timeout' | 'restart_stop_failed' | 'restart_start_failed' | 'unknown_error';
 /**
  * Failure codes for unregister operations
  */
@@ -202,7 +202,7 @@ interface StartupResult {
     /** Reason for failure (when success is false) */
     reason?: string;
     /** Error code (when success is false) */
-    code?: 'already_in_progress' | 'shutdown_in_progress' | 'dependency_cycle' | 'no_components_registered' | 'stalled_components_exist' | 'partial_state' | 'required_component_failed' | 'startup_timeout' | 'unknown_error';
+    code?: 'already_in_progress' | 'component_unexpected_stop' | 'shutdown_in_progress' | 'dependency_cycle' | 'no_components_registered' | 'stalled_components_exist' | 'partial_state' | 'required_component_failed' | 'startup_timeout' | 'unknown_error';
     /** Error object (when success is false due to dependency cycle or unknown error) */
     error?: Error;
     /** Total startup duration in milliseconds */
@@ -438,13 +438,20 @@ interface ValueResult<T = unknown> {
     code: 'found' | 'not_found' | 'stopped' | 'stalled' | 'no_handler' | 'error';
 }
 type EventEmitterSurface = Pick<EventEmitterProtected, 'on' | 'once' | 'hasListener' | 'hasListeners' | 'listenerCount'>;
+/**
+ * Public value lookup surface shared by LifecycleManager and component-scoped
+ * lifecycle references.
+ */
+interface LifecycleValueProvider {
+    getValue<T = unknown>(componentName: string, key: string, options?: GetValueOptions): ValueResult<T>;
+}
 /**
  * Common lifecycle interface shared by LifecycleManager and ComponentLifecycle
  *
  * Keep in sync with public LifecycleManager API and ComponentLifecycle proxy.
  * Purpose: define the shared surface both expose to avoid drift across the two.
  */
-interface LifecycleCommon extends EventEmitterSurface {
+interface LifecycleCommon extends EventEmitterSurface, LifecycleValueProvider {
     hasComponent(name: string): boolean;
     isComponentRunning(name: string): boolean;
     getComponentNames(): string[];
@@ -479,7 +486,6 @@ interface LifecycleCommon extends EventEmitterSurface {
     broadcastMessage(payload: unknown, options?: BroadcastOptions): Promise<BroadcastResult[]>;
     checkComponentHealth(name: string): Promise<HealthCheckResult>;
     checkAllHealth(): Promise<HealthReport>;
-    getValue<T = unknown>(componentName: string, key: string, options?: GetValueOptions): ValueResult<T>;
 }
 /**
  * Component-scoped lifecycle interface injected into BaseComponent
@@ -546,7 +552,7 @@ interface UnregisterOptions {
  * Options for starting all components
  */
 interface StartupOptions {
-    /** Allow start even if stalled components exist (default: false) */
+    /** Allow bulk startup to proceed by skipping stalled components (default: false) */
     ignoreStalledComponents?: boolean;
     /** Global timeout for entire startup process in milliseconds (default: constructor's startupTimeoutMS) */
     timeoutMS?: number;
@@ -956,6 +962,12 @@ declare abstract class BaseComponent {
     protected name: string;
     /** Reference to component-scoped lifecycle (set by manager when registered) */
     protected lifecycle: ComponentLifecycleRef;
+    /** @internal Set by LifecycleManager while the component is running. */
+    private _unexpectedStopHandler?;
+    /** @internal Incremented whenever the unexpected-stop handler is re-armed or cleared. */
+    private _unexpectedStopGeneration;
+    /** @internal Flag indicating whether this component is currently registered with a LifecycleManager */
+    private _isRegistered;
     /**
      * Create a new component
      *
@@ -964,6 +976,16 @@ declare abstract class BaseComponent {
      * @throws {InvalidComponentNameError} If name doesn't match kebab-case pattern
      */
     constructor(rootLogger: Logger, options: ComponentOptions);
+    /** @internal Called by LifecycleManager after a successful start. */
+    _setUnexpectedStopHandler(handler: (error?: Error) => boolean): void;
+    /** @internal Called by LifecycleManager when stop begins or component is unregistered. */
+    _clearUnexpectedStopHandler(): void;
+    /** @internal Called by LifecycleManager when registering the component. */
+    _markRegistered(): void;
+    /** @internal Called by LifecycleManager when unregistering the component. */
+    _markUnregistered(): void;
+    /** @internal Check if the component is registered with any LifecycleManager. */
+    _isRegisteredWithManager(): boolean;
     /**
      * Start the component
      *
@@ -1146,6 +1168,28 @@ declare abstract class BaseComponent {
      * Check if component is optional
      */
     isOptional(): boolean;
+    /**
+     * Run-scoped unexpected-stop callback. Rebound by LifecycleManager on each
+     * successful start so captured references from older runs go stale.
+     */
+    protected reportUnexpectedStop: (error?: Error) => boolean;
+    /**
+     * 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.
+     */
+    protected getSelfStatus(): ComponentStatus | undefined;
+    /**
+     * 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.
+     */
+    protected getUnexpectedStopReporter(): (error?: Error) => boolean;
 }
 
 /**
@@ -1179,7 +1223,11 @@ declare class LifecycleManager extends EventEmitterProtected implements Lifecycl
     private componentTimestamps;
     private componentErrors;
     private componentStartAttemptTokens;
+    private componentStopAttemptTokens;
+    private pendingForceStopWaiters;
+    private unexpectedStopsDuringStartup;
     private isStarting;
+    private autoAttachedSignalsDuringStartup;
     private isStarted;
     private isShuttingDown;
     private shutdownToken;
@@ -1592,6 +1640,45 @@ declare class LifecycleManager extends EventEmitterProtected implements Lifecycl
     private autoAttachSignals;
     private autoDetachSignalsIfIdle;
     private monitorLateStartupCompletion;
+    private consumeUnexpectedStopsDuringStartup;
+    /**
+     * 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.
+     */
+    private issueStopAttemptToken;
+    private createPendingForceStopWaiter;
+    private resolvePendingForceStopWaiters;
+    /**
+     * 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.
+     */
+    private handleLateStopResolution;
+    private handleComponentUnexpectedStop;
     /**
      * Safe emit wrapper - prevents event handler errors from breaking lifecycle
      */
@@ -1713,36 +1800,27 @@ declare class LifecycleManager extends EventEmitterProtected implements Lifecycl
      */
     private armRepeatedShutdownAfterFailure;
     /**
-     * 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
      */
+    private handleSignalRequest;
     private handleReloadRequest;
-    /**
-     * 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
-     */
     private handleInfoRequest;
+    private handleDebugRequest;
     /**
-     * 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
+     * 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.
      */
-    private handleDebugRequest;
+    private runSignalBroadcast;
     /**
      * Broadcast reload signal to all running components.
      * Calls onReload() on components that implement it.
@@ -1962,6 +2040,15 @@ interface LifecycleManagerEventMap {
         reason?: string;
         code?: string;
     };
+    'component:stalled-resolved': {
+        name: string;
+        stallInfo: ComponentStallInfo;
+        stalledDurationMS: number;
+    };
+    'component:unexpected-stop': {
+        name: string;
+        error?: Error;
+    };
     'component:shutdown-force-completed': {
         name: string;
     };
@@ -2140,6 +2227,8 @@ declare class LifecycleManagerEvents {
         reason?: string;
         code?: string;
     }): void;
+    componentStalledResolved(name: string, stallInfo: ComponentStallInfo, stalledDurationMS: number): void;
+    componentUnexpectedStop(name: string, error?: Error): void;
     componentShutdownForceCompleted(name: string): void;
     componentShutdownForceTimeout(name: string, timeoutMS: number): void;
     componentStartupRollback(name: string): void;
@@ -2329,4 +2418,4 @@ declare const lifecycleManagerErrCodes: {
     readonly StopTimeout: "StopTimeout";
 };
 
-export { BaseComponent, type BaseOperationResult, type BroadcastOptions, type BroadcastResult, type ComponentHealthResult, ComponentNotFoundError, type ComponentOperationFailureCode, type ComponentOperationResult, type ComponentOptions, ComponentRegistrationError, type ComponentSignalResult, type ComponentStallInfo, ComponentStartTimeoutError, ComponentStartupError, type ComponentState, type ComponentStatus, ComponentStopTimeoutError, type ComponentValueResult, DependencyCycleError, type DependencyValidationResult, type ForceShutdownContext, type GetValueOptions, type HealthCheckResult, type HealthReport, type InsertComponentAtResult, type InsertPosition, InvalidComponentNameError, LifecycleManager, type LifecycleManagerEmit, type LifecycleManagerEventMap, type LifecycleManagerEventName, LifecycleManagerEvents, type LifecycleManagerOptions, type LifecycleManagerStatus, type MessageResult, MissingDependencyError, type RegisterComponentResult, type RegisterOptions, type RegistrationFailureCode, type RepeatedShutdownRequestPolicy, type RestartComponentOptions, type RestartResult, type SendMessageOptions, type ShutdownEscalationStatus, type ShutdownMethod, type ShutdownResult, type SignalBroadcastResult, type StartComponentOptions, type StartupOptions, type StartupOrderFailureCode, type StartupOrderResult, type StartupResult, StartupTimeoutError, type StopAllOptions, type StopComponentOptions, type SystemState, type UnregisterComponentResult, type UnregisterFailureCode, type UnregisterOptions, type ValueResult, lifecycleManagerErrCodes, lifecycleManagerErrPrefix, lifecycleManagerErrTypes };
+export { BaseComponent, type BaseOperationResult, type BroadcastOptions, type BroadcastResult, type ComponentHealthResult, ComponentNotFoundError, type ComponentOperationFailureCode, type ComponentOperationResult, type ComponentOptions, ComponentRegistrationError, type ComponentSignalResult, type ComponentStallInfo, ComponentStartTimeoutError, ComponentStartupError, type ComponentState, type ComponentStatus, ComponentStopTimeoutError, type ComponentValueResult, DependencyCycleError, type DependencyValidationResult, type ForceShutdownContext, type GetValueOptions, type HealthCheckResult, type HealthReport, type InsertComponentAtResult, type InsertPosition, InvalidComponentNameError, LifecycleManager, type LifecycleManagerEmit, type LifecycleManagerEventMap, type LifecycleManagerEventName, LifecycleManagerEvents, type LifecycleManagerOptions, type LifecycleManagerStatus, type LifecycleValueProvider, type MessageResult, MissingDependencyError, type RegisterComponentResult, type RegisterOptions, type RegistrationFailureCode, type RepeatedShutdownRequestPolicy, type RestartComponentOptions, type RestartResult, type SendMessageOptions, type ShutdownEscalationStatus, type ShutdownMethod, type ShutdownResult, type SignalBroadcastResult, type StartComponentOptions, type StartupOptions, type StartupOrderFailureCode, type StartupOrderResult, type StartupResult, StartupTimeoutError, type StopAllOptions, type StopComponentOptions, type SystemState, type UnregisterComponentResult, type UnregisterFailureCode, type UnregisterOptions, type ValueResult, lifecycleManagerErrCodes, lifecycleManagerErrPrefix, lifecycleManagerErrTypes };

package/dist/lib/lifecycle-manager/index.d.ts

@@ -158,7 +158,7 @@ interface RestartComponentOptions {
 /**
  * Stable, machine-readable failure codes for individual component operations
  */
-type ComponentOperationFailureCode = 'component_not_found' | 'component_already_running' | 'component_already_starting' | 'component_already_stopping' | 'component_not_running' | 'component_stalled' | 'missing_dependency' | 'dependency_not_running' | 'has_running_dependents' | 'startup_in_progress' | 'shutdown_in_progress' | 'component_startup_timeout' | 'component_shutdown_timeout' | 'restart_stop_failed' | 'restart_start_failed' | 'unknown_error';
+type ComponentOperationFailureCode = 'component_not_found' | 'component_already_running' | 'component_already_starting' | 'component_already_stopping' | 'component_not_running' | 'component_stalled' | 'missing_dependency' | 'dependency_not_running' | 'has_running_dependents' | 'startup_in_progress' | 'shutdown_in_progress' | 'component_unexpected_stop' | 'component_startup_timeout' | 'component_shutdown_timeout' | 'restart_stop_failed' | 'restart_start_failed' | 'unknown_error';
 /**
  * Failure codes for unregister operations
  */
@@ -202,7 +202,7 @@ interface StartupResult {
     /** Reason for failure (when success is false) */
     reason?: string;
     /** Error code (when success is false) */
-    code?: 'already_in_progress' | 'shutdown_in_progress' | 'dependency_cycle' | 'no_components_registered' | 'stalled_components_exist' | 'partial_state' | 'required_component_failed' | 'startup_timeout' | 'unknown_error';
+    code?: 'already_in_progress' | 'component_unexpected_stop' | 'shutdown_in_progress' | 'dependency_cycle' | 'no_components_registered' | 'stalled_components_exist' | 'partial_state' | 'required_component_failed' | 'startup_timeout' | 'unknown_error';
     /** Error object (when success is false due to dependency cycle or unknown error) */
     error?: Error;
     /** Total startup duration in milliseconds */
@@ -438,13 +438,20 @@ interface ValueResult<T = unknown> {
     code: 'found' | 'not_found' | 'stopped' | 'stalled' | 'no_handler' | 'error';
 }
 type EventEmitterSurface = Pick<EventEmitterProtected, 'on' | 'once' | 'hasListener' | 'hasListeners' | 'listenerCount'>;
+/**
+ * Public value lookup surface shared by LifecycleManager and component-scoped
+ * lifecycle references.
+ */
+interface LifecycleValueProvider {
+    getValue<T = unknown>(componentName: string, key: string, options?: GetValueOptions): ValueResult<T>;
+}
 /**
  * Common lifecycle interface shared by LifecycleManager and ComponentLifecycle
  *
  * Keep in sync with public LifecycleManager API and ComponentLifecycle proxy.
  * Purpose: define the shared surface both expose to avoid drift across the two.
  */
-interface LifecycleCommon extends EventEmitterSurface {
+interface LifecycleCommon extends EventEmitterSurface, LifecycleValueProvider {
     hasComponent(name: string): boolean;
     isComponentRunning(name: string): boolean;
     getComponentNames(): string[];
@@ -479,7 +486,6 @@ interface LifecycleCommon extends EventEmitterSurface {
     broadcastMessage(payload: unknown, options?: BroadcastOptions): Promise<BroadcastResult[]>;
     checkComponentHealth(name: string): Promise<HealthCheckResult>;
     checkAllHealth(): Promise<HealthReport>;
-    getValue<T = unknown>(componentName: string, key: string, options?: GetValueOptions): ValueResult<T>;
 }
 /**
  * Component-scoped lifecycle interface injected into BaseComponent
@@ -546,7 +552,7 @@ interface UnregisterOptions {
  * Options for starting all components
  */
 interface StartupOptions {
-    /** Allow start even if stalled components exist (default: false) */
+    /** Allow bulk startup to proceed by skipping stalled components (default: false) */
     ignoreStalledComponents?: boolean;
     /** Global timeout for entire startup process in milliseconds (default: constructor's startupTimeoutMS) */
     timeoutMS?: number;
@@ -956,6 +962,12 @@ declare abstract class BaseComponent {
     protected name: string;
     /** Reference to component-scoped lifecycle (set by manager when registered) */
     protected lifecycle: ComponentLifecycleRef;
+    /** @internal Set by LifecycleManager while the component is running. */
+    private _unexpectedStopHandler?;
+    /** @internal Incremented whenever the unexpected-stop handler is re-armed or cleared. */
+    private _unexpectedStopGeneration;
+    /** @internal Flag indicating whether this component is currently registered with a LifecycleManager */
+    private _isRegistered;
     /**
      * Create a new component
      *
@@ -964,6 +976,16 @@ declare abstract class BaseComponent {
      * @throws {InvalidComponentNameError} If name doesn't match kebab-case pattern
      */
     constructor(rootLogger: Logger, options: ComponentOptions);
+    /** @internal Called by LifecycleManager after a successful start. */
+    _setUnexpectedStopHandler(handler: (error?: Error) => boolean): void;
+    /** @internal Called by LifecycleManager when stop begins or component is unregistered. */
+    _clearUnexpectedStopHandler(): void;
+    /** @internal Called by LifecycleManager when registering the component. */
+    _markRegistered(): void;
+    /** @internal Called by LifecycleManager when unregistering the component. */
+    _markUnregistered(): void;
+    /** @internal Check if the component is registered with any LifecycleManager. */
+    _isRegisteredWithManager(): boolean;
     /**
      * Start the component
      *
@@ -1146,6 +1168,28 @@ declare abstract class BaseComponent {
      * Check if component is optional
      */
     isOptional(): boolean;
+    /**
+     * Run-scoped unexpected-stop callback. Rebound by LifecycleManager on each
+     * successful start so captured references from older runs go stale.
+     */
+    protected reportUnexpectedStop: (error?: Error) => boolean;
+    /**
+     * 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.
+     */
+    protected getSelfStatus(): ComponentStatus | undefined;
+    /**
+     * 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.
+     */
+    protected getUnexpectedStopReporter(): (error?: Error) => boolean;
 }
 
 /**
@@ -1179,7 +1223,11 @@ declare class LifecycleManager extends EventEmitterProtected implements Lifecycl
     private componentTimestamps;
     private componentErrors;
     private componentStartAttemptTokens;
+    private componentStopAttemptTokens;
+    private pendingForceStopWaiters;
+    private unexpectedStopsDuringStartup;
     private isStarting;
+    private autoAttachedSignalsDuringStartup;
     private isStarted;
     private isShuttingDown;
     private shutdownToken;
@@ -1592,6 +1640,45 @@ declare class LifecycleManager extends EventEmitterProtected implements Lifecycl
     private autoAttachSignals;
     private autoDetachSignalsIfIdle;
     private monitorLateStartupCompletion;
+    private consumeUnexpectedStopsDuringStartup;
+    /**
+     * 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.
+     */
+    private issueStopAttemptToken;
+    private createPendingForceStopWaiter;
+    private resolvePendingForceStopWaiters;
+    /**
+     * 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.
+     */
+    private handleLateStopResolution;
+    private handleComponentUnexpectedStop;
     /**
      * Safe emit wrapper - prevents event handler errors from breaking lifecycle
      */
@@ -1713,36 +1800,27 @@ declare class LifecycleManager extends EventEmitterProtected implements Lifecycl
      */
     private armRepeatedShutdownAfterFailure;
     /**
-     * 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
      */
+    private handleSignalRequest;
     private handleReloadRequest;
-    /**
-     * 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
-     */
     private handleInfoRequest;
+    private handleDebugRequest;
     /**
-     * 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
+     * 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.
      */
-    private handleDebugRequest;
+    private runSignalBroadcast;
     /**
      * Broadcast reload signal to all running components.
      * Calls onReload() on components that implement it.
@@ -1962,6 +2040,15 @@ interface LifecycleManagerEventMap {
         reason?: string;
         code?: string;
     };
+    'component:stalled-resolved': {
+        name: string;
+        stallInfo: ComponentStallInfo;
+        stalledDurationMS: number;
+    };
+    'component:unexpected-stop': {
+        name: string;
+        error?: Error;
+    };
     'component:shutdown-force-completed': {
         name: string;
     };
@@ -2140,6 +2227,8 @@ declare class LifecycleManagerEvents {
         reason?: string;
         code?: string;
     }): void;
+    componentStalledResolved(name: string, stallInfo: ComponentStallInfo, stalledDurationMS: number): void;
+    componentUnexpectedStop(name: string, error?: Error): void;
     componentShutdownForceCompleted(name: string): void;
     componentShutdownForceTimeout(name: string, timeoutMS: number): void;
     componentStartupRollback(name: string): void;
@@ -2329,4 +2418,4 @@ declare const lifecycleManagerErrCodes: {
     readonly StopTimeout: "StopTimeout";
 };
 
-export { BaseComponent, type BaseOperationResult, type BroadcastOptions, type BroadcastResult, type ComponentHealthResult, ComponentNotFoundError, type ComponentOperationFailureCode, type ComponentOperationResult, type ComponentOptions, ComponentRegistrationError, type ComponentSignalResult, type ComponentStallInfo, ComponentStartTimeoutError, ComponentStartupError, type ComponentState, type ComponentStatus, ComponentStopTimeoutError, type ComponentValueResult, DependencyCycleError, type DependencyValidationResult, type ForceShutdownContext, type GetValueOptions, type HealthCheckResult, type HealthReport, type InsertComponentAtResult, type InsertPosition, InvalidComponentNameError, LifecycleManager, type LifecycleManagerEmit, type LifecycleManagerEventMap, type LifecycleManagerEventName, LifecycleManagerEvents, type LifecycleManagerOptions, type LifecycleManagerStatus, type MessageResult, MissingDependencyError, type RegisterComponentResult, type RegisterOptions, type RegistrationFailureCode, type RepeatedShutdownRequestPolicy, type RestartComponentOptions, type RestartResult, type SendMessageOptions, type ShutdownEscalationStatus, type ShutdownMethod, type ShutdownResult, type SignalBroadcastResult, type StartComponentOptions, type StartupOptions, type StartupOrderFailureCode, type StartupOrderResult, type StartupResult, StartupTimeoutError, type StopAllOptions, type StopComponentOptions, type SystemState, type UnregisterComponentResult, type UnregisterFailureCode, type UnregisterOptions, type ValueResult, lifecycleManagerErrCodes, lifecycleManagerErrPrefix, lifecycleManagerErrTypes };
+export { BaseComponent, type BaseOperationResult, type BroadcastOptions, type BroadcastResult, type ComponentHealthResult, ComponentNotFoundError, type ComponentOperationFailureCode, type ComponentOperationResult, type ComponentOptions, ComponentRegistrationError, type ComponentSignalResult, type ComponentStallInfo, ComponentStartTimeoutError, ComponentStartupError, type ComponentState, type ComponentStatus, ComponentStopTimeoutError, type ComponentValueResult, DependencyCycleError, type DependencyValidationResult, type ForceShutdownContext, type GetValueOptions, type HealthCheckResult, type HealthReport, type InsertComponentAtResult, type InsertPosition, InvalidComponentNameError, LifecycleManager, type LifecycleManagerEmit, type LifecycleManagerEventMap, type LifecycleManagerEventName, LifecycleManagerEvents, type LifecycleManagerOptions, type LifecycleManagerStatus, type LifecycleValueProvider, type MessageResult, MissingDependencyError, type RegisterComponentResult, type RegisterOptions, type RegistrationFailureCode, type RepeatedShutdownRequestPolicy, type RestartComponentOptions, type RestartResult, type SendMessageOptions, type ShutdownEscalationStatus, type ShutdownMethod, type ShutdownResult, type SignalBroadcastResult, type StartComponentOptions, type StartupOptions, type StartupOrderFailureCode, type StartupOrderResult, type StartupResult, StartupTimeoutError, type StopAllOptions, type StopComponentOptions, type SystemState, type UnregisterComponentResult, type UnregisterFailureCode, type UnregisterOptions, type ValueResult, lifecycleManagerErrCodes, lifecycleManagerErrPrefix, lifecycleManagerErrTypes };