@zerotal/scheduler 1.13.1 → 1.13.3

package/CHANGELOG.md

@@ -8,6 +8,17 @@ follows the Zerotal monorepo's unified versioning.
 
 ## [Unreleased]
 
+## [1.13.3] — 2026-08-31
+
+### Added
+
+- **A `zt doctor` check for schedules with nothing running them.** Schedules register in
+  `worker` and `console`, not `web` — the right design, and it means a second process is
+  required that the framework starts happily without.
+
+  Registered and never seen is a **failure**; registered and stale is a warning, because a
+  worker mid-restart is not a missing one. The scheduler beats every minute while running.
+
 ## [1.10.0] — 2026-08-30
 
 ### Fixed

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zerotal/scheduler",
-  "version": "1.13.1",
+  "version": "1.13.3",
   "license": "MIT",
   "maturity": "stable",
   "private": false,
@@ -30,7 +30,7 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@zerotal/core": "1.13.1"
+    "@zerotal/core": "1.13.3"
   },
   "devDependencies": {
     "typescript": "^5.8.0"

package/src/SchedulerManager.ts

@@ -1,6 +1,7 @@
 import { ScheduledTask } from "./ScheduledTask.ts";
 import type { TaskCallback } from "./ScheduledTask.ts";
 import { frameworkLog } from "@zerotal/core/logger";
+import { Heartbeat } from "@zerotal/core/heartbeat";
 
 export class SchedulerManager {
   private _tasks: Map<string, ScheduledTask> = new Map();
@@ -34,8 +35,15 @@ export class SchedulerManager {
    * stopped every schedule in the app. Which ones those are is not a thing you can
    * see from a crash loop.
    */
+  private _stopBeat: (() => void) | undefined;
+
   start(): void {
     this._started = true;
+    // Beat while running, so `zt doctor` can tell "schedules registered and a
+    // worker is running them" from "schedules registered and nothing is". The
+    // second is silent by nature: the web process has no way to notice, and the
+    // work simply does not happen.
+    this._stopBeat = Heartbeat.start("scheduler", { detail: `${this._tasks.size} task(s)` });
     for (const task of this._tasks.values()) {
       try {
         task.start();
@@ -51,6 +59,8 @@ export class SchedulerManager {
   }
 
   stop(): void {
+    this._stopBeat?.();
+    this._stopBeat = undefined;
     for (const task of this._tasks.values()) task.stop();
     this._started = false;
     frameworkLog("scheduler").info("All tasks stopped");

package/src/provider/SchedulerProvider.ts

@@ -8,6 +8,8 @@ import { schedulesConcern } from "../conventions.ts";
 import { installSchedulerObservability } from "../observability.ts";
 import { installSchedulerMonitor } from "../monitor.ts";
 import { FileScheduleRunStore, installScheduleRunLog, resolveRunLogConfig } from "../runLog.ts";
+import { workerLivenessCheck } from "@zerotal/core/heartbeat";
+import type { DoctorCheck } from "@zerotal/core";
 
 declare module "@zerotal/core" {
   interface ContainerBindings {
@@ -99,4 +101,31 @@ export class SchedulerProvider extends ServiceProvider {
     const scheduler = this.app.container.tryMake("scheduler") as SchedulerManager | undefined;
     scheduler?.stop();
   }
+
+  /**
+   * Report schedules registered with nothing running them.
+   *
+   * The reported production failure this exists for: an app ran for weeks with no
+   * worker process, and every scheduled task silently did not execute. Nothing
+   * logged, because from the web process's point of view nothing was wrong.
+   */
+  override doctorChecks(): DoctorCheck[] {
+    return [
+      workerLivenessCheck({
+        id: "scheduler-running",
+        label: "Scheduler",
+        name: "scheduler",
+        // Registered tasks, read from the manager rather than from config: a
+        // schedule that failed to register is not work anything can do.
+        hasWork: () => {
+          const count = this.app.container.tryMake("scheduler")?.tasks.size ?? 0;
+          return { has: count > 0, summary: `${count} schedule(s) registered` };
+        },
+        // Generous: the beat is every 60s, and a worker mid-restart should not
+        // read as a missing one.
+        staleAfter: 15 * 60,
+        command: "bun zt worker",
+      }),
+    ];
+  }
 }