@fluojs/cron 1.1.0 → 3.0.0

package/dist/module.js

@@ -1,14 +1,36 @@
 import { defineModule } from '@fluojs/runtime';
-import { CronLifecycleService } from './service.js';
+import { createCronRandomId } from './random-id.js';
 import { defaultCronScheduler } from './scheduler.js';
+import { CronLifecycleService } from './service.js';
 import { CRON_OPTIONS, SCHEDULING_REGISTRY } from './tokens.js';
 const DEFAULT_CRON_SHUTDOWN_TIMEOUT_MS = 10_000;
-function randomId() {
-  const randomUUID = globalThis.crypto?.randomUUID;
-  if (randomUUID) {
-    return randomUUID.call(globalThis.crypto);
+function normalizeRedisClientName(clientName) {
+  if (clientName === undefined) {
+    return undefined;
+  }
+  const normalizedClientName = clientName.trim();
+  if (normalizedClientName.length === 0) {
+    throw new Error('Cron distributed clientName must be a non-empty string when provided.');
   }
-  return `cron-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 10)}`;
+  return normalizedClientName;
+}
+function assertValidDistributedLockTtlMs(lockTtlMs) {
+  if (!Number.isFinite(lockTtlMs) || !Number.isInteger(lockTtlMs) || lockTtlMs < 1_000) {
+    throw new Error('Cron distributed lockTtlMs must be a positive integer greater than or equal to 1000ms.');
+  }
+}
+function normalizeDistributedOwnerId(ownerId) {
+  if (ownerId === undefined) {
+    return createCronRandomId();
+  }
+  if (typeof ownerId !== 'string') {
+    throw new Error('Cron distributed ownerId must be a string when provided.');
+  }
+  const normalizedOwnerId = ownerId.trim();
+  if (normalizedOwnerId.length === 0) {
+    throw new Error('Cron distributed ownerId must be a non-empty string when provided.');
+  }
+  return normalizedOwnerId;
 }
 function normalizeDistributedOptions(distributed) {
   if (distributed === undefined || distributed === false) {
@@ -17,7 +39,7 @@ function normalizeDistributedOptions(distributed) {
       enabled: false,
       keyPrefix: 'fluo:cron:lock',
       lockTtlMs: 30_000,
-      ownerId: randomId()
+      ownerId: createCronRandomId()
     };
   }
   if (distributed === true) {
@@ -26,16 +48,20 @@ function normalizeDistributedOptions(distributed) {
       enabled: true,
       keyPrefix: 'fluo:cron:lock',
       lockTtlMs: 30_000,
-      ownerId: randomId()
+      ownerId: createCronRandomId()
     };
   }
-  return {
-    clientName: distributed.clientName,
+  const normalizedDistributed = {
+    clientName: normalizeRedisClientName(distributed.clientName),
     enabled: distributed.enabled ?? true,
     keyPrefix: distributed.keyPrefix ?? 'fluo:cron:lock',
     lockTtlMs: distributed.lockTtlMs ?? 30_000,
-    ownerId: distributed.ownerId ?? randomId()
+    ownerId: normalizeDistributedOwnerId(distributed.ownerId)
   };
+  if (normalizedDistributed.enabled) {
+    assertValidDistributedLockTtlMs(normalizedDistributed.lockTtlMs);
+  }
+  return normalizedDistributed;
 }
 function normalizeShutdownOptions(shutdown) {
   const timeoutMs = shutdown?.timeoutMs ?? DEFAULT_CRON_SHUTDOWN_TIMEOUT_MS;

package/dist/random-id.d.ts

@@ -0,0 +1,3 @@
+/** Creates a platform-neutral random identifier for Cron ownership boundaries. */
+export declare function createCronRandomId(): string;
+//# sourceMappingURL=random-id.d.ts.map

package/dist/random-id.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"random-id.d.ts","sourceRoot":"","sources":["../src/random-id.ts"],"names":[],"mappings":"AAAA,kFAAkF;AAClF,wBAAgB,kBAAkB,IAAI,MAAM,CAQ3C"}

package/dist/random-id.js

@@ -0,0 +1,8 @@
+/** Creates a platform-neutral random identifier for Cron ownership boundaries. */
+export function createCronRandomId() {
+  const randomUUID = globalThis.crypto?.randomUUID;
+  if (randomUUID) {
+    return randomUUID.call(globalThis.crypto);
+  }
+  return `cron-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 10)}`;
+}

package/dist/service.d.ts

@@ -15,10 +15,11 @@ export declare class CronLifecycleService implements SchedulingRegistry, OnAppli
     private readonly logger;
     private readonly tasks;
     private readonly activeTasks;
-    private readonly runningDistributedLockKeys;
+    private readonly runningDistributedLeaseCounts;
     private readonly distributedLocks;
     private readonly taskRunner;
     private lifecycleState;
+    private shutdownDeadlineMs;
     private started;
     private shutdownPromise;
     constructor(options: NormalizedCronModuleOptions, runtimeContainer: Container, compiledModules: readonly CompiledModule[], logger: ApplicationLogger);
@@ -53,7 +54,7 @@ export declare class CronLifecycleService implements SchedulingRegistry, OnAppli
      * Removes a registered task by name.
      *
      * @param name Task name to remove.
-     * @returns `true` when a task existed and was removed.
+     * @returns `true` when a task existed and was removed; `false` when it was absent or its handle could not stop.
      */
     remove(name: string): boolean;
     /**
@@ -67,7 +68,7 @@ export declare class CronLifecycleService implements SchedulingRegistry, OnAppli
      * Disables a task without removing its descriptor.
      *
      * @param name Task name to disable.
-     * @returns `true` when the task exists after the operation.
+     * @returns `true` when the task exists and its handle stopped; `false` when it was absent or its handle could not stop.
      */
     disable(name: string): boolean;
     /**
@@ -88,6 +89,7 @@ export declare class CronLifecycleService implements SchedulingRegistry, OnAppli
      *
      * @param name Name of the cron task to update.
      * @param expression New cron expression to validate and schedule.
+     * @throws When validation, replacement scheduling, or previous-handle shutdown fails.
      */
     updateCronExpression(name: string, expression: string): void;
     /**
@@ -95,6 +97,7 @@ export declare class CronLifecycleService implements SchedulingRegistry, OnAppli
      *
      * @param name Name of the interval task to update.
      * @param ms New positive interval in milliseconds.
+     * @throws When validation, replacement scheduling, or previous-handle shutdown fails.
      */
     updateIntervalMs(name: string, ms: number): void;
     onApplicationBootstrap(): Promise<void>;
@@ -107,7 +110,10 @@ export declare class CronLifecycleService implements SchedulingRegistry, OnAppli
     private startLifecycle;
     private validateDistributedLockConfiguration;
     private handleStartupFailure;
+    private completeStartupFailureCleanupAfterActiveTasks;
+    private resetDistributedLocksAfterStartupFailure;
     private runShutdownLifecycle;
+    private getRemainingShutdownTimeoutMs;
     private getRunningDistributedLockKeys;
     private registerDecoratorTasks;
     private registerTask;
@@ -119,6 +125,7 @@ export declare class CronLifecycleService implements SchedulingRegistry, OnAppli
     private unscheduleTask;
     private stopScheduledHandle;
     private handleTaskTick;
+    private isTaskTickCurrent;
     private runTaskTick;
     private shouldUseDistributedExecution;
     private runDistributedTaskTick;

package/dist/service.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"service.d.ts","sourceRoot":"","sources":["../src/service.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"service.d.ts","sourceRoot":"","sources":["../src/service.ts"],"names":[],"mappings":"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"}

package/dist/service.js

@@ -9,7 +9,7 @@ import { APPLICATION_LOGGER, COMPILED_MODULES, RUNTIME_CONTAINER } from '@fluojs
 import { Cron as CronValidator } from 'croner';
 import { CronDistributedLockManager } from './distributed-lock-manager.js';
 import { createCronPlatformStatusSnapshot } from './status.js';
-import { createLockKey, discoverCronTaskDescriptors } from './task-discovery.js';
+import { assertValidSchedulingTaskName, createLockKey, discoverCronTaskDescriptors, resolveSchedulingTaskName } from './task-discovery.js';
 import { CronTaskRunner } from './task-runner.js';
 import { CRON_OPTIONS } from './tokens.js';
 function assertValidLockTtlMs(lockTtlMs) {
@@ -17,18 +17,8 @@ function assertValidLockTtlMs(lockTtlMs) {
     throw new Error('Cron distributed lockTtlMs must be a positive integer greater than or equal to 1000ms.');
   }
 }
-function assertValidTaskName(name) {
-  if (name.trim().length === 0) {
-    throw new Error('Scheduling task name must be a non-empty string.');
-  }
-}
 function resolveDynamicTaskName(name, optionName) {
-  assertValidTaskName(name);
-  if (optionName !== undefined) {
-    assertValidTaskName(optionName);
-    return optionName;
-  }
-  return name;
+  return resolveSchedulingTaskName(name, optionName);
 }
 function assertValidMs(ms, context) {
   if (!Number.isFinite(ms) || !Number.isInteger(ms) || ms <= 0) {
@@ -54,6 +44,9 @@ function createRedisDependencyId(name) {
   }
   return `redis.${normalizedName}`;
 }
+function getRemainingTimeoutMs(deadlineMs) {
+  return Math.max(0, deadlineMs - Date.now());
+}
 
 /**
  * Lifecycle-managed scheduler runtime for decorator-discovered and dynamic tasks.
@@ -69,10 +62,11 @@ class CronLifecycleService {
   }
   tasks = new Map();
   activeTasks = new Set();
-  runningDistributedLockKeys = new Set();
+  runningDistributedLeaseCounts = new Map();
   distributedLocks;
   taskRunner;
   lifecycleState = 'created';
+  shutdownDeadlineMs;
   started = false;
   shutdownPromise;
   constructor(options, runtimeContainer, compiledModules, logger) {
@@ -167,14 +161,16 @@ class CronLifecycleService {
    * Removes a registered task by name.
    *
    * @param name Task name to remove.
-   * @returns `true` when a task existed and was removed.
+   * @returns `true` when a task existed and was removed; `false` when it was absent or its handle could not stop.
    */
   remove(name) {
     const task = this.tasks.get(name);
     if (!task) {
       return false;
     }
-    this.unscheduleTask(task);
+    if (!this.unscheduleTask(task)) {
+      return false;
+    }
     this.tasks.delete(name);
     return true;
   }
@@ -211,7 +207,7 @@ class CronLifecycleService {
    * Disables a task without removing its descriptor.
    *
    * @param name Task name to disable.
-   * @returns `true` when the task exists after the operation.
+   * @returns `true` when the task exists and its handle stopped; `false` when it was absent or its handle could not stop.
    */
   disable(name) {
     const task = this.tasks.get(name);
@@ -222,8 +218,7 @@ class CronLifecycleService {
       return true;
     }
     task.enabled = false;
-    this.unscheduleTask(task);
-    return true;
+    return this.unscheduleTask(task);
   }
 
   /**
@@ -251,6 +246,7 @@ class CronLifecycleService {
    *
    * @param name Name of the cron task to update.
    * @param expression New cron expression to validate and schedule.
+   * @throws When validation, replacement scheduling, or previous-handle shutdown fails.
    */
   updateCronExpression(name, expression) {
     assertValidCronExpression(expression);
@@ -267,16 +263,23 @@ class CronLifecycleService {
     }
     const previousExpression = task.descriptor.expression;
     const previousHandle = task.scheduledHandle;
+    const previousToken = task.activeScheduleToken;
+    let nextHandle;
     task.descriptor.expression = expression;
     try {
-      const nextHandle = this.createScheduledHandle(task);
-      task.scheduledHandle = nextHandle;
+      nextHandle = this.createScheduledHandle(task);
       if (previousHandle) {
-        this.stopScheduledHandle(previousHandle);
+        previousHandle.stop();
       }
+      task.scheduledHandle = nextHandle;
+      task.activeScheduleToken = nextHandle.token;
     } catch (error) {
+      if (nextHandle) {
+        this.stopScheduledHandle(nextHandle);
+      }
       task.descriptor.expression = previousExpression;
       task.scheduledHandle = previousHandle;
+      task.activeScheduleToken = previousToken;
       throw error;
     }
   }
@@ -286,6 +289,7 @@ class CronLifecycleService {
    *
    * @param name Name of the interval task to update.
    * @param ms New positive interval in milliseconds.
+   * @throws When validation, replacement scheduling, or previous-handle shutdown fails.
    */
   updateIntervalMs(name, ms) {
     assertValidMs(ms, 'scheduling registry');
@@ -302,16 +306,23 @@ class CronLifecycleService {
     }
     const previousMs = task.descriptor.ms;
     const previousHandle = task.scheduledHandle;
+    const previousToken = task.activeScheduleToken;
+    let nextHandle;
     task.descriptor.ms = ms;
     try {
-      const nextHandle = this.createScheduledHandle(task);
-      task.scheduledHandle = nextHandle;
+      nextHandle = this.createScheduledHandle(task);
       if (previousHandle) {
-        this.stopScheduledHandle(previousHandle);
+        previousHandle.stop();
       }
+      task.scheduledHandle = nextHandle;
+      task.activeScheduleToken = nextHandle.token;
     } catch (error) {
+      if (nextHandle) {
+        this.stopScheduledHandle(nextHandle);
+      }
       task.descriptor.ms = previousMs;
       task.scheduledHandle = previousHandle;
+      task.activeScheduleToken = previousToken;
       throw error;
     }
   }
@@ -325,7 +336,7 @@ class CronLifecycleService {
       this.lifecycleState = 'ready';
     } catch (error) {
       this.lifecycleState = 'failed';
-      this.handleStartupFailure();
+      await this.handleStartupFailure();
       throw error;
     }
   }
@@ -362,7 +373,7 @@ class CronLifecycleService {
     });
   }
   toSchedulingTaskDescriptor(task) {
-    return {
+    return Object.freeze({
       distributed: task.descriptor.distributed,
       enabled: task.enabled,
       expression: task.descriptor.expression,
@@ -376,14 +387,16 @@ class CronLifecycleService {
       source: task.source,
       targetName: task.descriptor.targetName,
       timezone: task.descriptor.timezone
-    };
+    });
   }
   async shutdown() {
     if (this.shutdownPromise) {
       await this.shutdownPromise;
+      this.stopAllScheduledTasks();
       await this.retryReleasedDistributedLocksAfterShutdown();
       return;
     }
+    this.shutdownDeadlineMs = Date.now() + this.options.shutdown.timeoutMs;
     this.shutdownPromise = this.runShutdownLifecycle();
     await this.shutdownPromise;
   }
@@ -391,11 +404,11 @@ class CronLifecycleService {
     if (this.lifecycleState !== 'stopped' || this.activeTasks.size > 0) {
       return;
     }
-    await this.distributedLocks.releaseOwnedLocks();
+    await this.distributedLocks.releaseOwnedLocks(new Set(), this.getRemainingShutdownTimeoutMs());
   }
   async startLifecycle() {
-    await this.distributedLocks.resolveClient();
     this.validateDistributedLockConfiguration();
+    await this.distributedLocks.resolveClient();
     this.registerDecoratorTasks();
     this.started = true;
     this.scheduleEnabledTasks();
@@ -406,11 +419,30 @@ class CronLifecycleService {
     }
     assertValidLockTtlMs(this.options.distributed.lockTtlMs);
   }
-  handleStartupFailure() {
+  async handleStartupFailure() {
     this.started = false;
     this.stopAllScheduledTasks();
+    const startupRollbackTimedOut = await this.waitForActiveTasks();
+    if (startupRollbackTimedOut) {
+      this.logger.warn(`Cron startup rollback timed out after ${String(this.options.shutdown.timeoutMs)}ms with ${String(this.activeTasks.size)} active task(s) still pending.`, 'CronLifecycleService');
+    }
+    await this.distributedLocks.releaseOwnedLocks(startupRollbackTimedOut ? this.getRunningDistributedLockKeys() : new Set(), this.options.shutdown.timeoutMs);
     this.tasks.clear();
-    this.distributedLocks.reset();
+    if (this.activeTasks.size > 0) {
+      void this.completeStartupFailureCleanupAfterActiveTasks();
+      return;
+    }
+    this.resetDistributedLocksAfterStartupFailure();
+  }
+  async completeStartupFailureCleanupAfterActiveTasks() {
+    await this.drainActiveTasks();
+    await this.distributedLocks.releaseOwnedLocks(new Set(), this.options.shutdown.timeoutMs);
+    this.resetDistributedLocksAfterStartupFailure();
+  }
+  resetDistributedLocksAfterStartupFailure() {
+    if (this.distributedLocks.ownedLocks === 0) {
+      this.distributedLocks.reset();
+    }
   }
   async runShutdownLifecycle() {
     this.lifecycleState = 'stopping';
@@ -420,11 +452,14 @@ class CronLifecycleService {
     if (shutdownTimedOut) {
       this.logger.warn(`Cron shutdown timed out after ${String(this.options.shutdown.timeoutMs)}ms with ${String(this.activeTasks.size)} active task(s) still pending.`, 'CronLifecycleService');
     }
-    await this.distributedLocks.releaseOwnedLocks(shutdownTimedOut ? this.getRunningDistributedLockKeys() : new Set());
+    await this.distributedLocks.releaseOwnedLocks(shutdownTimedOut ? this.getRunningDistributedLockKeys() : new Set(), this.getRemainingShutdownTimeoutMs());
     this.lifecycleState = 'stopped';
   }
+  getRemainingShutdownTimeoutMs() {
+    return this.shutdownDeadlineMs === undefined ? this.options.shutdown.timeoutMs : getRemainingTimeoutMs(this.shutdownDeadlineMs);
+  }
   getRunningDistributedLockKeys() {
-    return new Set(this.runningDistributedLockKeys);
+    return new Set(this.runningDistributedLeaseCounts.keys());
   }
   registerDecoratorTasks() {
     const descriptors = discoverCronTaskDescriptors(this.compiledModules, this.options, this.logger);
@@ -433,11 +468,13 @@ class CronLifecycleService {
     }
   }
   registerTask(descriptor, source) {
+    assertValidSchedulingTaskName(descriptor.taskName);
     this.assertTaskNameAvailable(descriptor.taskName);
-    if (descriptor.distributed) {
+    if (this.options.distributed.enabled && descriptor.distributed) {
       assertValidLockTtlMs(descriptor.lockTtlMs);
     }
     const task = {
+      activeScheduleToken: undefined,
       descriptor,
       enabled: true,
       running: false,
@@ -445,7 +482,7 @@ class CronLifecycleService {
       source
     };
     if (this.started) {
-      task.scheduledHandle = this.createScheduledHandle(task);
+      this.scheduleTask(task);
     }
     this.tasks.set(descriptor.taskName, task);
   }
@@ -465,22 +502,36 @@ class CronLifecycleService {
     if (!task.enabled || task.scheduledHandle) {
       return;
     }
-    task.scheduledHandle = this.createScheduledHandle(task);
+    const previousToken = task.activeScheduleToken;
+    const nextToken = {};
+    task.activeScheduleToken = nextToken;
+    try {
+      task.scheduledHandle = this.createScheduledHandle(task, nextToken);
+    } catch (error) {
+      task.activeScheduleToken = previousToken;
+      throw error;
+    }
   }
-  createScheduledHandle(task) {
+  createScheduledHandle(task, token = {}) {
     const taskName = task.descriptor.taskName;
     if (task.descriptor.kind === 'cron') {
       const expression = task.descriptor.expression;
       if (!expression) {
         throw new Error(`Cron task "${taskName}" is missing a cron expression.`);
       }
-      return this.options.scheduler(expression, {
+      const scheduledHandle = this.options.scheduler(expression, {
         name: taskName,
         protect: true,
         timezone: task.descriptor.timezone
       }, async () => {
-        await this.handleTaskTick(taskName);
+        await this.handleTaskTick(taskName, token);
       });
+      return {
+        stop: () => {
+          scheduledHandle.stop();
+        },
+        token
+      };
     }
     const ms = task.descriptor.ms;
     if (!ms) {
@@ -488,54 +539,63 @@ class CronLifecycleService {
     }
     if (task.descriptor.kind === 'interval') {
       const timer = setInterval(() => {
-        void this.handleTaskTick(taskName);
+        void this.handleTaskTick(taskName, token);
       }, ms);
       return {
         stop: () => {
           clearInterval(timer);
-        }
+        },
+        token
       };
     }
     const timer = setTimeout(() => {
-      void this.handleTaskTick(taskName).finally(() => {
-        this.completeTimeoutTask(taskName);
+      void this.handleTaskTick(taskName, token).finally(() => {
+        this.completeTimeoutTask(taskName, token);
       });
     }, ms);
     return {
       stop: () => {
         clearTimeout(timer);
-      }
+      },
+      token
     };
   }
-  completeTimeoutTask(taskName) {
+  completeTimeoutTask(taskName, token) {
     const task = this.tasks.get(taskName);
-    if (!task || task.descriptor.kind !== 'timeout') {
+    if (!task || task.descriptor.kind !== 'timeout' || task.activeScheduleToken !== token) {
       return;
     }
     task.scheduledHandle = undefined;
+    task.activeScheduleToken = undefined;
     task.enabled = false;
   }
   unscheduleTask(task) {
     if (!task.scheduledHandle) {
-      return;
+      return true;
     }
     const scheduledHandle = task.scheduledHandle;
+    if (!this.stopScheduledHandle(scheduledHandle)) {
+      return false;
+    }
     task.scheduledHandle = undefined;
-    this.stopScheduledHandle(scheduledHandle);
+    task.activeScheduleToken = undefined;
+    return true;
   }
   stopScheduledHandle(scheduledHandle) {
     try {
       scheduledHandle.stop();
+      return true;
     } catch (error) {
       this.logger.error('Failed to stop scheduled task.', error, 'CronLifecycleService');
+      return false;
     }
   }
-  async handleTaskTick(taskName) {
+  async handleTaskTick(taskName, token) {
     const taskState = this.tasks.get(taskName);
-    if (!taskState?.enabled || taskState.running) {
+    if (!this.started || !this.isTaskTickCurrent(taskName, token, taskState) || taskState.running) {
       return;
     }
-    const task = this.runTaskTick(taskState.descriptor, taskState);
+    const task = this.runTaskTick(taskState.descriptor, taskState, token);
     taskState.running = true;
     this.activeTasks.add(task);
     try {
@@ -545,23 +605,30 @@ class CronLifecycleService {
       this.activeTasks.delete(task);
     }
   }
-  async runTaskTick(descriptor, taskState) {
+  isTaskTickCurrent(taskName, token, taskState) {
+    return this.lifecycleState !== 'stopping' && this.lifecycleState !== 'stopped' && taskState?.enabled === true && this.tasks.get(taskName) === taskState && taskState.activeScheduleToken === token;
+  }
+  async runTaskTick(descriptor, taskState, token) {
     if (!this.shouldUseDistributedExecution(descriptor)) {
       await this.executeTask(descriptor, taskState);
       return;
     }
-    await this.runDistributedTaskTick(descriptor, taskState);
+    await this.runDistributedTaskTick(descriptor, taskState, token);
   }
   shouldUseDistributedExecution(descriptor) {
     return this.options.distributed.enabled && descriptor.distributed && this.distributedLocks.resolvedClient !== undefined;
   }
-  async runDistributedTaskTick(descriptor, taskState) {
-    const lockAcquired = await this.distributedLocks.tryAcquireLock(descriptor);
-    if (!lockAcquired) {
+  async runDistributedTaskTick(descriptor, taskState, token) {
+    const lease = await this.distributedLocks.tryAcquireLock(descriptor);
+    if (!lease) {
       return;
     }
-    const lockRenewalMonitor = this.distributedLocks.startLockRenewalMonitor(descriptor);
-    this.runningDistributedLockKeys.add(descriptor.lockKey);
+    if (this.lifecycleState !== 'failed' && !this.isTaskTickCurrent(descriptor.taskName, token, taskState)) {
+      await this.distributedLocks.releaseLock(lease, this.shutdownPromise ? this.getRemainingShutdownTimeoutMs() : undefined);
+      return;
+    }
+    const lockRenewalMonitor = this.distributedLocks.startLockRenewalMonitor(descriptor, lease);
+    this.runningDistributedLeaseCounts.set(descriptor.lockKey, (this.runningDistributedLeaseCounts.get(descriptor.lockKey) ?? 0) + 1);
     try {
       await this.executeTask(descriptor, taskState, async () => {
         lockRenewalMonitor.stop();
@@ -569,10 +636,15 @@ class CronLifecycleService {
       });
     } finally {
       lockRenewalMonitor.stop();
-      this.runningDistributedLockKeys.delete(descriptor.lockKey);
-      const released = await this.distributedLocks.releaseLock(descriptor);
+      const runningLeaseCount = this.runningDistributedLeaseCounts.get(descriptor.lockKey);
+      if (runningLeaseCount === 1) {
+        this.runningDistributedLeaseCounts.delete(descriptor.lockKey);
+      } else if (runningLeaseCount !== undefined) {
+        this.runningDistributedLeaseCounts.set(descriptor.lockKey, runningLeaseCount - 1);
+      }
+      const released = await this.distributedLocks.releaseLock(lease, this.shutdownPromise ? this.getRemainingShutdownTimeoutMs() : undefined);
       if (!released && this.lifecycleState === 'stopped') {
-        await this.distributedLocks.releaseOwnedLocks();
+        await this.distributedLocks.releaseOwnedLocks(this.getRunningDistributedLockKeys(), this.getRemainingShutdownTimeoutMs());
       }
     }
   }
@@ -580,7 +652,8 @@ class CronLifecycleService {
     if (this.activeTasks.size === 0) {
       return false;
     }
-    if (this.options.shutdown.timeoutMs === 0) {
+    const timeoutMs = this.getRemainingShutdownTimeoutMs();
+    if (timeoutMs === 0) {
       return true;
     }
     let timeoutHandle;
@@ -588,7 +661,7 @@ class CronLifecycleService {
       return await Promise.race([this.drainActiveTasks().then(() => false), new Promise(resolve => {
         timeoutHandle = setTimeout(() => {
           resolve(true);
-        }, this.options.shutdown.timeoutMs);
+        }, timeoutMs);
       })]);
     } finally {
       if (timeoutHandle) {
@@ -606,6 +679,7 @@ class CronLifecycleService {
     if (descriptor.kind === 'timeout') {
       taskState.enabled = false;
       taskState.scheduledHandle = undefined;
+      taskState.activeScheduleToken = undefined;
     }
   }
   stopAllScheduledTasks() {

package/dist/task-discovery.d.ts

@@ -1,4 +1,4 @@
-import { type MetadataPropertyKey } from '@fluojs/core';
+import type { MetadataPropertyKey } from '@fluojs/core';
 import type { ApplicationLogger, CompiledModule } from '@fluojs/runtime';
 import type { CronTaskDescriptor, NormalizedCronModuleOptions } from './types.js';
 /**
@@ -17,6 +17,20 @@ export declare function buildDefaultTaskName(targetName: string, methodName: str
  * @returns The create lock key result.
  */
 export declare function createLockKey(prefix: string, taskName: string): string;
+/**
+ * Asserts that a scheduling task name can be used as a registry key.
+ *
+ * @param name Scheduling task name supplied by a decorator or registry call.
+ */
+export declare function assertValidSchedulingTaskName(name: string): void;
+/**
+ * Resolves the effective scheduling task name while preserving authored names.
+ *
+ * @param defaultName Name derived from the decorated target or registry argument.
+ * @param optionName Optional name override supplied in scheduling options.
+ * @returns The effective task name used by the scheduler registry.
+ */
+export declare function resolveSchedulingTaskName(defaultName: string, optionName?: string): string;
 /**
  * Method key to name.
  *