nvent 0.4.5 → 0.5.0

package/dist/runtime/events/utils/scheduleTrigger.js

@@ -0,0 +1,69 @@
+import { useNventLogger, useScheduler } from "#imports";
+import { getEventBus } from "../eventBus.js";
+export async function scheduleTrigger(triggerName, scheduleConfig, triggerStatus) {
+  const logger = useNventLogger("trigger-wiring");
+  const scheduler = useScheduler();
+  const eventBus = getEventBus();
+  try {
+    const jobId = `trigger:${triggerName}`;
+    const handler = async () => {
+      logger.debug("Schedule trigger fired", { trigger: triggerName });
+      await eventBus.publish({
+        type: "trigger.fired",
+        triggerName,
+        data: {
+          scheduledAt: Date.now(),
+          timezone: scheduleConfig.timezone || "UTC"
+        }
+      });
+    };
+    await scheduler.unschedule(jobId);
+    const jobConfig = {
+      id: jobId,
+      type: scheduleConfig.cron ? "cron" : "interval",
+      name: `Schedule Trigger: ${triggerName}`,
+      handler,
+      metadata: {
+        triggerName,
+        type: "schedule-trigger",
+        scheduleConfig
+      },
+      enabled: triggerStatus === "active"
+    };
+    if (scheduleConfig.cron) {
+      jobConfig.cron = scheduleConfig.cron;
+      jobConfig.timezone = scheduleConfig.timezone || "UTC";
+    } else if (scheduleConfig.interval) {
+      jobConfig.interval = scheduleConfig.interval * 1e3;
+    }
+    await scheduler.schedule(jobConfig);
+    logger.info("Scheduled trigger", {
+      trigger: triggerName,
+      cron: scheduleConfig.cron,
+      interval: scheduleConfig.interval,
+      timezone: scheduleConfig.timezone
+    });
+  } catch (error) {
+    logger.error("Failed to schedule trigger", {
+      trigger: triggerName,
+      error: error instanceof Error ? error.message : String(error)
+    });
+    throw error;
+  }
+}
+export async function unscheduleTrigger(triggerName) {
+  const logger = useNventLogger("trigger-wiring");
+  const scheduler = useScheduler();
+  try {
+    const jobId = `trigger:${triggerName}`;
+    const removed = await scheduler.unschedule(jobId);
+    if (removed) {
+      logger.info("Unscheduled trigger", { trigger: triggerName });
+    }
+  } catch (error) {
+    logger.error("Failed to unschedule trigger", {
+      trigger: triggerName,
+      error: error instanceof Error ? error.message : String(error)
+    });
+  }
+}

package/dist/runtime/events/utils/stallDetector.d.ts

@@ -43,18 +43,37 @@ export declare class FlowStallDetector {
     private store;
     private config;
     private logger;
-    private intervalId?;
+    private schedulerJobId?;
     private started;
     constructor(store: StoreAdapter, config?: StallDetectorConfig);
     /**
      * Start the periodic stall detector
      * Should be called once per instance after adapters are initialized
+     * Runs startup recovery to clean up flows from previous server instances
      */
-    start(): void;
+    start(): Promise<void>;
+    /**
+     * Get the configuration for scheduling
+     * Returns config needed by flowWiring to register the scheduler job
+     */
+    getScheduleConfig(): {
+        enabled: boolean;
+        interval: number;
+        stallTimeout: number;
+    };
+    /**
+     * Set the scheduler job ID (called from flowWiring after scheduling)
+     */
+    setSchedulerJobId(jobId: string): void;
     /**
      * Stop the periodic stall detector
      */
-    stop(): void;
+    stop(): Promise<void>;
+    /**
+     * Get stall timeout for a specific flow
+     * Uses flow-specific timeout from analyzed metadata, falls back to global config
+     */
+    private getFlowStallTimeout;
     /**
      * Update activity timestamp for a flow
      * Should be called on every step event (started, completed, failed, retry)
@@ -63,6 +82,7 @@ export declare class FlowStallDetector {
     /**
      * Check if a specific flow is stalled (lazy detection)
      * Returns true if the flow should be marked as stalled
+     * v0.5: Await-aware - uses flow-specific timeout and skips awaiting flows
      */
     isStalled(flowName: string, runId: string): Promise<boolean>;
     /**
@@ -78,6 +98,27 @@ export declare class FlowStallDetector {
      * For now, we'll need to pass flow names to check, or iterate known flows from registry.
      */
     checkFlowsForStalls(flowNames: string[]): Promise<void>;
+    /**
+     * Run startup recovery to clean up flows left in running state from previous server instance
+     * This marks all running flows as stalled since their in-memory state is lost
+     * Also validates and cleans up flow stats index
+     */
+    private runStartupRecovery;
+    /**
+     * Validate flow stats index and remove entries for non-existent flows
+     * Also corrects running/awaiting counts based on actual scanned data
+     *
+     * NOTE: We only validate running/awaiting counts because:
+     * - They are small snapshot values (usually < 100)
+     * - We already scanned all flows during startup recovery
+     * - Discrepancies indicate actual bugs (flows stuck in wrong state)
+     *
+     * We do NOT validate total/success/failure/cancel because:
+     * - These are cumulative counters that can be millions in production
+     * - Validation would require full table scan (prohibitively expensive)
+     * - Minor discrepancies don't affect runtime behavior
+     */
+    private validateFlowStats;
     /**
      * Internal method for periodic checks
      * Gets flow names from registry and checks them

package/dist/runtime/events/utils/stallDetector.js

@@ -1,11 +1,11 @@
-import { useNventLogger, useStreamTopics } from "#imports";
+import { useNventLogger, useStreamTopics, $useAnalyzedFlows, useScheduler } from "#imports";
 const DEFAULT_STALL_TIMEOUT = 30 * 60 * 1e3;
 const DEFAULT_CHECK_INTERVAL = 15 * 60 * 1e3;
 export class FlowStallDetector {
   store;
   config;
   logger = useNventLogger("stall-detector");
-  intervalId;
+  schedulerJobId;
   started = false;
   constructor(store, config = {}) {
     this.store = store;
@@ -18,92 +18,115 @@ export class FlowStallDetector {
   /**
    * Start the periodic stall detector
    * Should be called once per instance after adapters are initialized
+   * Runs startup recovery to clean up flows from previous server instances
    */
-  start() {
+  async start() {
     if (this.started) {
       this.logger.warn("Stall detector already started");
       return;
     }
     this.started = true;
-    if (this.config.enablePeriodicCheck) {
-      this.logger.info("Starting periodic stall detector", {
-        stallTimeout: `${this.config.stallTimeout / 1e3}s`,
-        checkInterval: `${this.config.checkInterval / 1e3}s`
-      });
-      setTimeout(() => {
-        this.checkAllRunningFlows();
-      }, 60 * 1e3);
-      this.intervalId = setInterval(() => {
-        this.checkAllRunningFlows();
-      }, this.config.checkInterval);
-    } else {
-      this.logger.info("Periodic stall detector disabled, using lazy detection only");
-    }
+    await this.runStartupRecovery();
+    this.logger.info(`Stall detector started - periodicCheck: ${this.config.enablePeriodicCheck}, stallTimeout: ${this.config.stallTimeout / 1e3}s, checkInterval: ${this.config.checkInterval / 1e3}s`);
+  }
+  /**
+   * Get the configuration for scheduling
+   * Returns config needed by flowWiring to register the scheduler job
+   */
+  getScheduleConfig() {
+    return {
+      enabled: this.config.enablePeriodicCheck,
+      interval: this.config.checkInterval,
+      stallTimeout: this.config.stallTimeout
+    };
+  }
+  /**
+   * Set the scheduler job ID (called from flowWiring after scheduling)
+   */
+  setSchedulerJobId(jobId) {
+    this.schedulerJobId = jobId;
   }
   /**
    * Stop the periodic stall detector
    */
-  stop() {
-    if (this.intervalId) {
-      clearInterval(this.intervalId);
-      this.intervalId = void 0;
-      this.logger.info("Stopped periodic stall detector");
+  async stop() {
+    if (this.schedulerJobId) {
+      try {
+        const scheduler = useScheduler();
+        await scheduler.unschedule(this.schedulerJobId);
+        this.schedulerJobId = void 0;
+        this.logger.info("Stopped periodic stall detector");
+      } catch (error) {
+        this.logger.error(`Failed to stop stall detector: ${error.message}`);
+      }
     }
     this.started = false;
   }
+  /**
+   * Get stall timeout for a specific flow
+   * Uses flow-specific timeout from analyzed metadata, falls back to global config
+   */
+  async getFlowStallTimeout(flowName) {
+    try {
+      const analyzedFlows = $useAnalyzedFlows();
+      const flowMeta = analyzedFlows.find((f) => f.id === flowName);
+      if (flowMeta?.stallTimeout) {
+        this.logger.debug(`Using flow-specific stall timeout for '${flowName}': ${flowMeta.stallTimeout / 1e3}s`);
+        return flowMeta.stallTimeout;
+      }
+    } catch (error) {
+      this.logger.warn(`Failed to get flow-specific stall timeout for '${flowName}': ${error.message}`);
+    }
+    return this.config.stallTimeout;
+  }
   /**
    * Update activity timestamp for a flow
    * Should be called on every step event (started, completed, failed, retry)
    */
   async updateActivity(flowName, runId) {
-    const { SubjectPatterns } = useStreamTopics();
-    const indexKey = SubjectPatterns.flowRunIndex(flowName);
+    const { StoreSubjects } = useStreamTopics();
+    const indexKey = StoreSubjects.flowRunIndex(flowName);
     try {
-      if (!this.store.indexUpdate) {
+      if (!this.store.index.update) {
         this.logger.warn("Store does not support indexUpdate, cannot update activity");
         return;
       }
-      await this.store.indexUpdate(indexKey, runId, {
+      await this.store.index.update(indexKey, runId, {
         lastActivityAt: Date.now()
       });
     } catch (error) {
-      this.logger.warn("Failed to update flow activity", {
-        flowName,
-        runId,
-        error: error.message
-      });
+      this.logger.warn(`Failed to update flow activity for '${flowName}' runId '${runId}': ${error.message}`);
     }
   }
   /**
    * Check if a specific flow is stalled (lazy detection)
    * Returns true if the flow should be marked as stalled
+   * v0.5: Await-aware - uses flow-specific timeout and skips awaiting flows
    */
   async isStalled(flowName, runId) {
-    const { SubjectPatterns } = useStreamTopics();
-    const indexKey = SubjectPatterns.flowRunIndex(flowName);
+    const { StoreSubjects } = useStreamTopics();
+    const indexKey = StoreSubjects.flowRunIndex(flowName);
     try {
-      if (!this.store.indexGet) return false;
-      const flowEntry = await this.store.indexGet(indexKey, runId);
+      if (!this.store.index.get) return false;
+      const flowEntry = await this.store.index.get(indexKey, runId);
       if (!flowEntry?.metadata) return false;
       if (flowEntry.metadata.status !== "running") return false;
+      const awaitingSteps = flowEntry.metadata.awaitingSteps || {};
+      const hasActiveAwaits = Object.keys(awaitingSteps).length > 0;
+      if (hasActiveAwaits) {
+        this.logger.debug(`Flow '${flowName}' runId '${runId}' has active awaits [${Object.keys(awaitingSteps).join(", ")}], skipping stall check`);
+        return false;
+      }
+      const stallTimeout = await this.getFlowStallTimeout(flowName);
       const lastActivity = flowEntry.metadata.lastActivityAt || flowEntry.metadata.startedAt || 0;
       const timeSinceActivity = Date.now() - lastActivity;
-      if (timeSinceActivity > this.config.stallTimeout) {
-        this.logger.info("Flow detected as stalled (lazy check)", {
-          flowName,
-          runId,
-          timeSinceActivity: `${Math.round(timeSinceActivity / 1e3)}s`,
-          stallTimeout: `${this.config.stallTimeout / 1e3}s`
-        });
+      if (timeSinceActivity > stallTimeout) {
+        this.logger.info(`Flow detected as stalled (lazy check) - '${flowName}' runId '${runId}': ${Math.round(timeSinceActivity / 1e3)}s since activity (timeout: ${stallTimeout / 1e3}s)`);
         return true;
       }
       return false;
     } catch (error) {
-      this.logger.warn("Failed to check if flow is stalled", {
-        flowName,
-        runId,
-        error: error.message
-      });
+      this.logger.warn(`Failed to check if flow is stalled for '${flowName}' runId '${runId}': ${error.message}`);
       return false;
     }
   }
@@ -112,43 +135,40 @@ export class FlowStallDetector {
    * Emits a flow.stalled event and updates the flow status
    */
   async markAsStalled(flowName, runId, reason = "No activity timeout") {
-    const { SubjectPatterns } = useStreamTopics();
-    const indexKey = SubjectPatterns.flowRunIndex(flowName);
+    const { StoreSubjects } = useStreamTopics();
+    const indexKey = StoreSubjects.flowRunIndex(flowName);
     try {
-      if (!this.store.indexGet) {
+      if (!this.store.index.get) {
         this.logger.warn("Store does not support indexGet, cannot mark as stalled");
         return;
       }
-      const flowEntry = await this.store.indexGet(indexKey, runId);
+      const flowEntry = await this.store.index.get(indexKey, runId);
       if (!flowEntry?.metadata) return;
-      if (flowEntry.metadata.status !== "running") return;
-      if (this.store.indexUpdate) {
-        await this.store.indexUpdate(indexKey, runId, {
+      const previousStatus = flowEntry.metadata.status;
+      if (previousStatus !== "running" && previousStatus !== "awaiting") return;
+      if (this.store.index.update) {
+        await this.store.index.update(indexKey, runId, {
           status: "stalled",
+          previousStatus,
+          // Track what state it was in before stalling
           stalledAt: Date.now(),
           stallReason: reason
         });
       }
-      const streamName = SubjectPatterns.flowRun(runId);
-      await this.store.append(streamName, {
+      const streamName = StoreSubjects.flowRun(runId);
+      await this.store.stream.append(streamName, {
         type: "flow.stalled",
         runId,
         flowName,
         data: {
-          reason
+          reason,
+          previousStatus
+          // Include previous status so stats handler knows which counter to decrement
         }
       });
-      this.logger.info("Marked flow as stalled", {
-        flowName,
-        runId,
-        reason
-      });
+      this.logger.info(`Marked flow as stalled - '${flowName}' runId '${runId}': ${reason}`);
     } catch (error) {
-      this.logger.error("Failed to mark flow as stalled", {
-        flowName,
-        runId,
-        error: error.message
-      });
+      this.logger.error(`Failed to mark flow as stalled for '${flowName}' runId '${runId}': ${error.message}`);
     }
   }
   /**
@@ -159,54 +179,235 @@ export class FlowStallDetector {
    * For now, we'll need to pass flow names to check, or iterate known flows from registry.
    */
   async checkFlowsForStalls(flowNames) {
-    this.logger.debug("Running periodic stall check", { flows: flowNames.length });
+    this.logger.info(`Running periodic stall check for ${flowNames.length} flows`);
     try {
-      if (!this.store.indexGet || !this.store.indexRead) {
+      if (!this.store.index.get || !this.store.index.read) {
         this.logger.warn("Store does not support required index operations");
         return;
       }
-      const { SubjectPatterns } = useStreamTopics();
+      const { StoreSubjects } = useStreamTopics();
       let checkedCount = 0;
       let stalledCount = 0;
       for (const flowName of flowNames) {
-        const indexKey = SubjectPatterns.flowRunIndex(flowName);
-        const entries = await this.store.indexRead(indexKey, { limit: 1e3 });
+        const indexKey = StoreSubjects.flowRunIndex(flowName);
+        const flowStallTimeout = await this.getFlowStallTimeout(flowName);
+        const entries = await this.store.index.read(indexKey, { limit: 1e3 });
         for (const entry of entries) {
           if (!entry.metadata) continue;
           checkedCount++;
-          if (entry.metadata.status !== "running") continue;
+          if (entry.metadata.status !== "running" && entry.metadata.status !== "awaiting") continue;
+          const awaitingSteps = entry.metadata.awaitingSteps || {};
+          const awaitingStepNames = Object.keys(awaitingSteps);
+          if (awaitingStepNames.length > 0) {
+            let hasOverdueAwaits = false;
+            let hasLegacyAwait = false;
+            for (const stepName of awaitingStepNames) {
+              const awaitState = awaitingSteps[stepName];
+              if (awaitState?.status === "awaiting") {
+                if (!awaitState.timeoutAt) {
+                  hasLegacyAwait = true;
+                } else if (Date.now() > awaitState.timeoutAt) {
+                  hasOverdueAwaits = true;
+                  break;
+                }
+              }
+            }
+            if (hasOverdueAwaits) {
+              await this.markAsStalled(flowName, entry.id, "Await pattern timed out");
+              stalledCount++;
+              continue;
+            }
+            if (hasLegacyAwait) {
+              this.logger.debug(`Skipping flow with legacy await (no timeout) - '${flowName}' runId '${entry.id}'`);
+            }
+            continue;
+          }
           const lastActivity = entry.metadata.lastActivityAt || entry.metadata.startedAt || 0;
           const timeSinceActivity = Date.now() - lastActivity;
-          if (timeSinceActivity > this.config.stallTimeout) {
+          if (timeSinceActivity > flowStallTimeout) {
             await this.markAsStalled(flowName, entry.id, "Periodic check detected no activity");
             stalledCount++;
           }
         }
       }
-      if (stalledCount > 0) {
-        this.logger.info("Periodic stall check completed", {
-          checked: checkedCount,
-          stalled: stalledCount
-        });
-      } else {
-        this.logger.debug("Periodic stall check completed", {
-          checked: checkedCount,
-          stalled: 0
-        });
-      }
+      this.logger.info(`Periodic stall check completed - checked: ${checkedCount}, stalled: ${stalledCount}`);
     } catch (error) {
       this.logger.error("Failed to run periodic stall check", {
         error: error.message
       });
     }
   }
+  /**
+   * Run startup recovery to clean up flows left in running state from previous server instance
+   * This marks all running flows as stalled since their in-memory state is lost
+   * Also validates and cleans up flow stats index
+   */
+  async runStartupRecovery() {
+    this.logger.info("Running startup recovery to check for orphaned flows and validate stats");
+    try {
+      if (!this.store.index.get || !this.store.index.read) {
+        this.logger.warn("Store does not support required index operations");
+        return;
+      }
+      const analyzedFlows = $useAnalyzedFlows();
+      const flowNames = analyzedFlows.map((f) => f.id).filter(Boolean);
+      this.logger.info(`Starting flow recovery check for ${flowNames.length} registered flows: [${flowNames.join(", ")}]`);
+      if (flowNames.length === 0) {
+        this.logger.debug("No flows registered, skipping startup recovery");
+        return;
+      }
+      const { StoreSubjects } = useStreamTopics();
+      let recoveredCount = 0;
+      const actualCounts = {};
+      for (const flowName of flowNames) {
+        actualCounts[flowName] = { running: 0, awaiting: 0 };
+        const indexKey = StoreSubjects.flowRunIndex(flowName);
+        this.logger.debug(`Reading flow run index for '${flowName}': ${indexKey}`);
+        const entries = await this.store.index.read(indexKey, { limit: 1e3 });
+        const statusCounts = {};
+        for (const entry of entries) {
+          if (!entry.metadata) {
+            this.logger.debug(`Skipping entry without metadata - '${flowName}' runId '${entry.id}'`);
+            continue;
+          }
+          const status = entry.metadata.status || "unknown";
+          statusCounts[status] = (statusCounts[status] || 0) + 1;
+          if (status === "running") {
+            actualCounts[flowName].running++;
+          } else if (status === "awaiting") {
+            actualCounts[flowName].awaiting++;
+          }
+          if (entry.metadata.status === "running" || entry.metadata.status === "awaiting") {
+            const awaitingSteps = entry.metadata.awaitingSteps || {};
+            const awaitingStepNames = Object.keys(awaitingSteps);
+            this.logger.info(`Found flow in ${entry.metadata.status} state - '${flowName}' runId '${entry.id}' with ${awaitingStepNames.length} awaiting steps`);
+            this.logger.debug(`Flow '${flowName}' runId '${entry.id}' status: ${entry.metadata.status}, awaitingSteps: ${awaitingStepNames.length}`);
+            if (awaitingStepNames.length > 0) {
+              let hasActiveValidAwaits = false;
+              let hasOverdueAwaits = false;
+              for (const stepName of awaitingStepNames) {
+                const awaitState = awaitingSteps[stepName];
+                this.logger.info(`Checking await state for '${flowName}' runId '${entry.id}' step '${stepName}': status=${awaitState?.status}, timeoutAt=${awaitState?.timeoutAt}, resolveAt=${awaitState?.resolveAt}`);
+                if (awaitState?.status === "awaiting") {
+                  const timeoutAt = awaitState.timeoutAt || awaitState.resolveAt;
+                  if (!timeoutAt) {
+                    hasActiveValidAwaits = true;
+                    this.logger.warn(`Found await without timeout (legacy data) - '${flowName}' runId '${entry.id}' step '${stepName}' - treating as valid (timeout tracking was added later)`);
+                  } else if (Date.now() > timeoutAt) {
+                    hasOverdueAwaits = true;
+                    this.logger.warn(`Found overdue await pattern - '${flowName}' runId '${entry.id}' step '${stepName}': timeoutAt=${new Date(timeoutAt).toISOString()}, overdueBy=${Math.round((Date.now() - timeoutAt) / 1e3)}s`);
+                  } else {
+                    hasActiveValidAwaits = true;
+                    this.logger.debug(`Found active valid await - '${flowName}' runId '${entry.id}' step '${stepName}': remaining=${Math.round((timeoutAt - Date.now()) / 1e3)}s`);
+                  }
+                }
+              }
+              if (hasOverdueAwaits) {
+                this.logger.info(`Marking flow as stalled (overdue awaits) - '${flowName}' runId '${entry.id}'`);
+                await this.markAsStalled(flowName, entry.id, "Await pattern resolution failed or expired");
+                recoveredCount++;
+                continue;
+              }
+              if (hasActiveValidAwaits) {
+                if (entry.metadata.status === "running") {
+                  if (this.store.index.update) {
+                    await this.store.index.update(indexKey, entry.id, {
+                      status: "awaiting"
+                    });
+                    this.logger.info(`Updated flow status to awaiting (has active awaits) - '${flowName}' runId '${entry.id}' steps: [${awaitingStepNames.join(", ")}]`);
+                  }
+                } else {
+                  this.logger.debug(`Flow already has awaiting status - '${flowName}' runId '${entry.id}'`);
+                }
+                continue;
+              }
+            }
+            this.logger.info(`Marking flow as stalled (no active awaits) - '${flowName}' runId '${entry.id}'`);
+            await this.markAsStalled(flowName, entry.id, "Server restart - flow state lost");
+            recoveredCount++;
+          }
+        }
+        const statusSummary = Object.entries(statusCounts).map(([status, count]) => `${status}:${count}`).join(", ");
+        this.logger.info(`Flow recovery summary for '${flowName}' - total: ${entries.length}, statuses: {${statusSummary}}`);
+      }
+      await this.validateFlowStats(flowNames, actualCounts);
+      if (recoveredCount > 0) {
+        this.logger.info(`Startup recovery completed - marked ${recoveredCount} orphaned flow(s) as stalled`);
+      } else {
+        this.logger.debug("Startup recovery completed - no orphaned flows found");
+      }
+    } catch (error) {
+      this.logger.error(`Failed to run startup recovery: ${error.message}`);
+    }
+  }
+  /**
+   * Validate flow stats index and remove entries for non-existent flows
+   * Also corrects running/awaiting counts based on actual scanned data
+   *
+   * NOTE: We only validate running/awaiting counts because:
+   * - They are small snapshot values (usually < 100)
+   * - We already scanned all flows during startup recovery
+   * - Discrepancies indicate actual bugs (flows stuck in wrong state)
+   *
+   * We do NOT validate total/success/failure/cancel because:
+   * - These are cumulative counters that can be millions in production
+   * - Validation would require full table scan (prohibitively expensive)
+   * - Minor discrepancies don't affect runtime behavior
+   */
+  async validateFlowStats(validFlowNames, actualCounts) {
+    this.logger.debug("Validating flow stats index");
+    try {
+      if (!this.store.index.read || !this.store.index.delete || !this.store.index.update) {
+        this.logger.debug("Store does not support stats validation operations");
+        return;
+      }
+      const { StoreSubjects } = useStreamTopics();
+      const statsIndexKey = StoreSubjects.flowIndex();
+      const statsEntries = await this.store.index.read(statsIndexKey, { limit: 1e4 });
+      let removedCount = 0;
+      let correctedCount = 0;
+      for (const entry of statsEntries) {
+        const flowName = entry.id;
+        if (!validFlowNames.includes(flowName)) {
+          this.logger.info(`Removing stats for non-existent flow '${flowName}'`);
+          await this.store.index.delete(statsIndexKey, flowName);
+          removedCount++;
+          continue;
+        }
+        if (!entry.metadata?.stats) {
+          this.logger.warn(`Flow stats entry missing stats object for '${flowName}'`);
+          continue;
+        }
+        const stats = entry.metadata.stats;
+        const actual = actualCounts[flowName] || { running: 0, awaiting: 0 };
+        const runningMismatch = stats.running !== actual.running;
+        const awaitingMismatch = stats.awaiting !== actual.awaiting;
+        if (runningMismatch || awaitingMismatch) {
+          this.logger.warn(`Flow stats mismatch detected for '${flowName}' - stored: running=${stats.running} awaiting=${stats.awaiting}, actual: running=${actual.running} awaiting=${actual.awaiting} - correcting`);
+          await this.store.index.update(statsIndexKey, flowName, {
+            stats: {
+              running: actual.running,
+              awaiting: actual.awaiting
+            }
+          });
+          correctedCount++;
+        }
+      }
+      if (removedCount > 0 || correctedCount > 0) {
+        this.logger.info(`Flow stats validation completed - removed ${removedCount} orphaned stats, corrected ${correctedCount} running/awaiting counts`);
+      } else {
+        this.logger.debug("Flow stats validation completed - all stats accurate");
+      }
+    } catch (error) {
+      this.logger.error(`Failed to validate flow stats: ${error.message}`);
+    }
+  }
   /**
    * Internal method for periodic checks
    * Gets flow names from registry and checks them
    */
   async checkAllRunningFlows() {
     try {
-      const { $useAnalyzedFlows } = await import("#imports");
       const analyzedFlows = $useAnalyzedFlows();
       const flowNames = analyzedFlows.map((f) => f.id).filter(Boolean);
       if (flowNames.length === 0) {
@@ -215,9 +416,7 @@ export class FlowStallDetector {
       }
       await this.checkFlowsForStalls(flowNames);
     } catch (error) {
-      this.logger.error("Failed to run periodic stall check", {
-        error: error.message
-      });
+      this.logger.error(`Failed to run periodic stall check: ${error.message}`);
     }
   }
   /**