@zerotal/scheduler 1.4.0 → 1.5.1

package/CHANGELOG.md

@@ -8,6 +8,46 @@ follows the Zerotal monorepo's unified versioning.
 
 ## [Unreleased]
 
+## [1.5.0] — 2026-08-15
+
+### Changed
+
+- **`withoutOverlapping`'s cross-process lock defaults to 5 minutes, not 24 hours.** The
+  lock could not be extended, so its TTL had to cover the longest the task might ever run
+  — and a scheduler that died mid-run therefore blocked that task for a full day. The lock
+  is now heartbeated while the task runs, so the TTL only has to outlive a missed beat.
+
+  `expiresAfterMinutes` keeps working and **changes meaning**: it is now "how long after a
+  crash before another host may take this task over", not "how long the task may take". A
+  long-running task no longer needs a long value; set one only if you want a crash to be
+  slower to recover from. `{ refresh: false }` restores the old behaviour.
+
+  A failed heartbeat does not kill the run. It is logged and the handle dropped — the task
+  is already in flight, and stopping it half-finished because another host may now also be
+  running does not un-overlap anything, it just adds a second failure.
+
+### Added
+
+- **Durable run history.** Every completed execution (success or failure) is appended to
+  a capped JSONL file under `storage/framework/`, so "did the retention sweep run last
+  night?" has an answer that survives a restart — previously the only record was
+  in-memory task state and whatever the log rotation kept. Read it with the new
+  **`bun zt schedule:runs [name]`** (`--limit` to page), through the monitor panel, or
+  via `ScheduleRunStore.recent()`. The store is bound as `scheduler.runs` — rebind it to
+  move the history elsewhere. Configured under `scheduler.runLog` (`enabled`, `path`,
+  `keep`); on by default except under `APP_ENV=test`. A torn tail from a crash
+  mid-append is repaired on the next write instead of eating the following record.
+- **The monitor panel survives restarts.** The scheduled-tasks section now falls back to
+  the recorded history when the in-memory state is empty, marking those values
+  "(recorded)", and gained a "Recent runs" table — a task that ran an hour ago no longer
+  reads "Never run" after a deploy.
+- **Static schedule config is called out.** `static cron = "…"` typechecks (it merely
+  declares a new static) and registers nothing, while `static` is exactly the convention
+  models (`static fillable`) and Flow components (`static layout`) use — the natural
+  first attempt fails silently. Convention discovery now warns at registration, names
+  the misdeclared keys, and the finding is surfaced by `bun zt doctor` too
+  (`staticScheduleConfigKeys` is exported for reuse).
+
 ## [1.0.3] — 2026-08-07
 
 ### Changed

package/package.json

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

package/src/ScheduledTask.ts

@@ -48,8 +48,31 @@ export interface OverlapLockOptions {
    */
   crossProcess?: boolean;
 
-  /** Lock TTL safety net, in minutes, so a crashed run can't deadlock the key. Default: 1440 (24h). */
+  /**
+   * **How long after a crash before another host may take the task over**, in
+   * minutes. Default: 5.
+   *
+   * This used to mean "how long the task might possibly run", which is why it
+   * defaulted to a day: the lock could not be extended, so the TTL had to cover
+   * the worst case, and a scheduler that died mid-run blocked that task until
+   * the next afternoon. The lock is now heartbeated while the task runs, so the
+   * TTL only has to outlive one missed heartbeat — and the number you are
+   * choosing is a recovery time rather than a guess about duration.
+   *
+   * A long-running task no longer needs a long value here. Set one only if you
+   * want a crash to be *slower* to recover from, which is rarely what anyone
+   * wants.
+   */
   expiresAfterMinutes?: number;
+
+  /**
+   * Heartbeat the lock for as long as the task runs. Default: `true`.
+   *
+   * Turning it off restores the old behaviour, where the task must finish
+   * inside {@link expiresAfterMinutes} or lose its lock — and where you must
+   * therefore size that value for the worst case.
+   */
+  refresh?: boolean;
 }
 
 export class ScheduledTask {
@@ -85,8 +108,15 @@ export class ScheduledTask {
   private _emailOutputTo: string | undefined = undefined;
 
   private _crossProcess: boolean = false;
-  private _lockTtlMs: number = 24 * 60 * 60 * 1000;
+  /**
+   * Minutes, not a day. The lock is heartbeated while the task runs, so this is
+   * the window in which a crashed scheduler still holds the key — not a bound on
+   * how long the task may take.
+   */
+  private _lockTtlMs: number = 5 * 60 * 1000;
+  private _lockRefresh: boolean = true;
   private _lockHandle: ManagedLock | undefined = undefined;
+  private _lockHeartbeat: ReturnType<typeof setInterval> | undefined = undefined;
 
   static outputMailer: OutputMailer | undefined = undefined;
 
@@ -126,6 +156,7 @@ export class ScheduledTask {
   withoutOverlapping(options?: OverlapLockOptions): this {
     this._skipIfStillRunning = true;
     this._crossProcess = options?.crossProcess ?? true;
+    this._lockRefresh = options?.refresh ?? true;
     if (options?.expiresAfterMinutes !== undefined) {
       this._lockTtlMs = Math.max(1, options.expiresAfterMinutes) * 60 * 1000;
     }
@@ -278,11 +309,62 @@ export class ScheduledTask {
     const ttlSeconds = Math.max(1, Math.ceil(this._lockTtlMs / 1000));
     const handle = manager.lock(`schedule:${this._name}`, ttlSeconds);
     const acquired = await handle.acquire();
-    if (acquired) this._lockHandle = handle;
-    return acquired;
+    if (!acquired) return false;
+
+    this._lockHandle = handle;
+    if (this._lockRefresh) this._startHeartbeat(handle, ttlSeconds);
+    return true;
+  }
+
+  /**
+   * Keep the overlap lock alive while the task runs.
+   *
+   * A third of the TTL, so one missed beat is survivable. A failed refresh is
+   * *not* escalated: the run is already in flight, and killing a half-finished
+   * task because another host may now also be running it does not make the
+   * overlap un-happen — it just adds a second failure. It is logged, the handle
+   * is dropped so the release cannot touch a lock we no longer own, and the task
+   * is left to finish.
+   */
+  private _startHeartbeat(handle: ManagedLock, ttlSeconds: number): void {
+    // A third of the TTL, floored only low enough to stop a pathological TTL
+    // spinning. The floor must never approach the interval itself: at 1000ms it
+    // made every TTL of three seconds or less refresh at the moment of expiry —
+    // a heartbeat that reliably lost the race it existed to win.
+    const everyMs = Math.max(50, Math.floor((ttlSeconds * 1000) / 3));
+    const timer = setInterval(() => {
+      void handle.refresh().then(
+        (ok) => {
+          if (ok) return;
+          frameworkLog("scheduler").warn(
+            `Lost the overlap lock for "${this._name}" — another host may now run it too.`,
+            { task: this._name },
+          );
+          this._stopHeartbeat();
+          this._lockHandle = undefined;
+        },
+        () => {
+          /* transient driver error — the next beat tries again */
+        },
+      );
+    }, everyMs);
+    // The scheduler outlives any one task, but a CLI or a dev-mode process that
+    // stops mid-run must still be able to exit.
+    timer.unref?.();
+    this._lockHeartbeat = timer;
+  }
+
+  private _stopHeartbeat(): void {
+    if (this._lockHeartbeat) {
+      clearInterval(this._lockHeartbeat);
+      this._lockHeartbeat = undefined;
+    }
   }
 
   private async _releaseLock(): Promise<void> {
+    // Stopped first and unconditionally: a beat that fires after the release
+    // would re-acquire the key this task has just finished with.
+    this._stopHeartbeat();
     if (this._lockHandle) {
       await this._lockHandle.release();
       this._lockHandle = undefined;

package/src/SchedulerManager.ts

@@ -6,6 +6,13 @@ export class SchedulerManager {
   private _tasks: Map<string, ScheduledTask> = new Map();
   private _started: boolean = false;
 
+  /**
+   * Schedule classes found declaring config as `static` during convention
+   * discovery (which registers nothing — config is instance properties).
+   * Written by the schedules concern, read by the scheduler's doctor check.
+   */
+  readonly staticConfigFindings: Array<{ className: string; keys: string[] }> = [];
+
   add(name: string, cronExpression: string, callback: TaskCallback): ScheduledTask {
     const task = new ScheduledTask(name, cronExpression, callback);
     this._tasks.set(name, task);

package/src/commands/ScheduleRunsCommand.ts

@@ -0,0 +1,63 @@
+import type { Application } from "@zerotal/core";
+import { Command } from "@zerotal/core";
+import type { ArgDef, FlagDef } from "@zerotal/core";
+import type { ScheduleRunStore } from "../runLog.ts";
+
+/**
+ * `bun zt schedule:runs [name]` — the durable run history. Answers "did the
+ * retention sweep run last night?" from the on-disk record, which survives
+ * restarts — unlike the in-memory last-run state `schedule:list` reflects.
+ */
+export class ScheduleRunsCommand extends Command {
+  static override commandName = "schedule:runs";
+  static override description = "Show recent scheduled-task runs (durable, survives restarts)";
+  static override needsApp = true;
+
+  // The optional positional arg filters to one task's runs.
+  static override args: ArgDef[] = [{ name: "name", required: false }];
+
+  static override flags: FlagDef[] = [
+    {
+      name: "limit",
+      short: "n",
+      type: "number",
+      description: "How many runs to show",
+      default: 20,
+    },
+  ];
+
+  async run(): Promise<void> {
+    const app = this.app as Application | undefined;
+    const store = app?.container.tryMake("scheduler.runs") as ScheduleRunStore | undefined;
+
+    if (!store) {
+      this.error("Run store not registered. Add SchedulerProvider to your providers.");
+      return;
+    }
+
+    const name = this.args["name"];
+    const limit = Number(this.flags["limit"] ?? 20);
+    const runs = store.recent(limit, name);
+
+    if (runs.length === 0) {
+      this.info(
+        name
+          ? `No recorded runs for "${name}". (The run log records completed executions; ` +
+              `it is off under APP_ENV=test.)`
+          : "No recorded runs yet.",
+      );
+      return;
+    }
+
+    this.section(name ? `Runs of ${name} (${runs.length})` : `Recent runs (${runs.length})`);
+    for (const run of runs) {
+      this.table([
+        ["Task", run.name],
+        ["Started", run.startedAt],
+        ["Duration", `${run.durationMs} ms`],
+        ["Result", run.ok ? "OK" : `FAILED — ${run.error ?? "unknown error"}`],
+      ]);
+      this.newLine();
+    }
+  }
+}

package/src/commands/index.ts

@@ -1 +1,2 @@
 export { ScheduleListCommand } from "./ScheduleListCommand.ts";
+export { ScheduleRunsCommand } from "./ScheduleRunsCommand.ts";

package/src/config.ts

@@ -1,13 +1,27 @@
 import { deepMerge } from "@zerotal/core";
+import { DEFAULT_RUN_LOG_KEEP, DEFAULT_RUN_LOG_PATH } from "./runLog.ts";
 
 export interface SchedulerConfigShape {
   /** Timezone for cron expressions. Informational only - Bun.cron uses
    *  the system timezone. Default: 'UTC' */
   timezone: string;
+  /** Durable run history — read with `schedule:runs` (see runLog.ts). */
+  runLog: {
+    /** Default: on, except under `APP_ENV=test`. */
+    enabled?: boolean;
+    /** JSONL file path, relative to the app root. */
+    path: string;
+    /** Records kept after compaction; the file is compacted at 2× this. */
+    keep: number;
+  };
 }
 
 const defaults: SchedulerConfigShape = {
   timezone: "UTC",
+  runLog: {
+    path: DEFAULT_RUN_LOG_PATH,
+    keep: DEFAULT_RUN_LOG_KEEP,
+  },
 };
 
 /**

package/src/conventions.ts

@@ -12,6 +12,46 @@ function isScheduleClass(v: unknown): v is new () => Schedule {
   );
 }
 
+/** Every declarative setting `registerSchedule` reads off a Schedule instance. */
+const SCHEDULE_CONFIG_KEYS = [
+  "name",
+  "cron",
+  "frequency",
+  "timezone",
+  "withoutOverlapping",
+  "environments",
+  "inBackground",
+  "between",
+  "unlessBetween",
+  "pingBefore",
+  "pingAfter",
+  "pingOnSuccess",
+  "pingOnFailure",
+  "appendOutputTo",
+  "emailOutputTo",
+  "when",
+  "skip",
+] as const;
+
+/**
+ * Config keys declared as `static` on a Schedule class. Schedule config is instance
+ * properties, but `static cron = "…"` typechecks (it simply declares a new static) and
+ * registers nothing — matching the `static` convention used by models (`static fillable`)
+ * and Flow components (`static layout`) closely enough to be the natural first attempt.
+ * Exported for the doctor.
+ */
+export function staticScheduleConfigKeys(cls: abstract new () => Schedule): string[] {
+  return SCHEDULE_CONFIG_KEYS.filter((key) => {
+    const desc = Object.getOwnPropertyDescriptor(cls, key);
+    if (desc === undefined) return false;
+    // Every class carries an intrinsic non-enumerable `name`; a `static name = "…"`
+    // field is enumerable, which is what tells the two apart. Static *methods*
+    // (`static frequency() {}`) are non-enumerable by spec, so the other keys are
+    // checked by presence alone — no intrinsic shares their names.
+    return key === "name" ? desc.enumerable === true : true;
+  });
+}
+
 /**
  * Register one Schedule instance with the scheduler manager, translating its declarative
  * settings into a configured ScheduledTask. Exported for testing.
@@ -75,6 +115,15 @@ export const schedulesConcern: ConcernDescriptor = {
     }
     for (const exported of Object.values(mod)) {
       if (!isScheduleClass(exported)) continue;
+      const misdeclared = staticScheduleConfigKeys(exported);
+      if (misdeclared.length > 0) {
+        frameworkLog("scheduler").warn(
+          `Schedule "${exported.name}" declares static ${misdeclared.join(", ")} — ` +
+            `schedule config is instance properties, so static values register nothing. ` +
+            `Drop the \`static\` keyword (e.g. \`override cron = "0 3 * * *"\`).`,
+        );
+        manager.staticConfigFindings.push({ className: exported.name, keys: misdeclared });
+      }
       registerSchedule(manager, new exported(), exported.name);
     }
   },

package/src/index.ts

@@ -24,3 +24,13 @@ export type { SchedulerConfigShape } from "./config.ts";
 
 // Framework instrumentation events (emitted on the core FrameworkEvents bus)
 export { TaskRan, TaskFailed, TaskSkipped } from "./events.ts";
+
+// Durable run history (schedule:runs, the monitor panel, or ScheduleRunStore.recent()).
+export {
+  FileScheduleRunStore,
+  installScheduleRunLog,
+  resolveRunLogConfig,
+  DEFAULT_RUN_LOG_PATH,
+  DEFAULT_RUN_LOG_KEEP,
+} from "./runLog.ts";
+export type { ScheduleRunStore, ScheduleRunRecord, RunLogConfig } from "./runLog.ts";

package/src/monitor.ts

@@ -80,8 +80,20 @@ export function installSchedulerMonitor(app: Application): void {
     resolve: () => {
       const scheduler = app.container.tryMake("scheduler") as SchedulerManager | null;
       const tasks = scheduler ? [...scheduler.tasks.values()] : [];
-      const failing = tasks.filter((t) => t.lastOk === false);
-      const neverRun = tasks.filter((t) => t.lastRunAt === undefined);
+      // The durable run log fills what the in-memory state cannot: after a restart
+      // every task reads "never run" in memory even when it ran an hour ago.
+      const runStore = app.container.tryMake("scheduler.runs") ?? undefined;
+      const lastRecorded = (name: string) => {
+        try {
+          return runStore?.lastFor(name);
+        } catch {
+          return undefined;
+        }
+      };
+      const failing = tasks.filter((t) => (t.lastOk ?? lastRecorded(t.name)?.ok) === false);
+      const neverRun = tasks.filter(
+        (t) => t.lastRunAt === undefined && lastRecorded(t.name) === undefined,
+      );
 
       return {
         stats: [
@@ -112,25 +124,62 @@ export function installSchedulerMonitor(app: Application): void {
               {
                 key: "status",
                 label: "Last result",
-                tone: (v) => (v === "Failed" ? "bad" : v === "OK" ? "good" : null),
+                tone: (v) =>
+                  String(v).startsWith("Failed")
+                    ? "bad"
+                    : String(v).startsWith("OK")
+                      ? "good"
+                      : null,
               },
               { key: "lastRunAt", label: "Last run", format: formatWhen },
               { key: "durationMs", label: "Duration", align: "end", format: formatDuration },
               { key: "nextRunAt", label: "Next run", format: formatWhen },
             ],
-            rows: tasks.map((t) => ({
-              name: t.name,
-              schedule: t.schedule,
-              status: t.isRunning
-                ? "Running"
-                : t.lastOk === undefined
-                  ? "Never run"
-                  : t.lastOk
-                    ? "OK"
-                    : "Failed",
-              lastRunAt: t.lastRunAt ?? null,
-              durationMs: t.lastDurationMs ?? null,
-              nextRunAt: t.nextRunAt(),
+            rows: tasks.map((t) => {
+              // Fall back to the recorded run when this process has not run the
+              // task yet — "(recorded)" marks the value as pre-restart history.
+              const recorded = t.lastRunAt === undefined ? lastRecorded(t.name) : undefined;
+              const lastOk = t.lastOk ?? recorded?.ok;
+              return {
+                name: t.name,
+                schedule: t.schedule,
+                status: t.isRunning
+                  ? "Running"
+                  : lastOk === undefined
+                    ? "Never run"
+                    : lastOk
+                      ? recorded
+                        ? "OK (recorded)"
+                        : "OK"
+                      : recorded
+                        ? "Failed (recorded)"
+                        : "Failed",
+                lastRunAt: t.lastRunAt ?? recorded?.finishedAt ?? null,
+                durationMs: t.lastDurationMs ?? recorded?.durationMs ?? null,
+                nextRunAt: t.nextRunAt(),
+              };
+            }),
+          },
+          {
+            title: "Recent runs",
+            empty: "No runs recorded yet.",
+            columns: [
+              { key: "name", label: "Task" },
+              {
+                key: "result",
+                label: "Result",
+                tone: (v) => (v === "OK" ? "good" : "bad"),
+              },
+              { key: "startedAt", label: "Started", format: formatWhen },
+              { key: "durationMs", label: "Duration", align: "end", format: formatDuration },
+              { key: "error", label: "Error" },
+            ],
+            rows: (runStore?.recent(15) ?? []).map((r) => ({
+              name: r.name,
+              result: r.ok ? "OK" : "Failed",
+              startedAt: r.startedAt,
+              durationMs: r.durationMs,
+              error: r.error ?? "—",
             })),
           },
         ],

package/src/provider/SchedulerProvider.ts

@@ -1,11 +1,13 @@
 import { ServiceProvider } from "@zerotal/core";
 import type { AppEnvironment } from "@zerotal/core";
 import type { LockManager } from "@zerotal/core/lock";
+import { resolve } from "node:path";
 import { SchedulerManager } from "../SchedulerManager.ts";
 import { ScheduledTask } from "../ScheduledTask.ts";
 import { schedulesConcern } from "../conventions.ts";
 import { installSchedulerObservability } from "../observability.ts";
 import { installSchedulerMonitor } from "../monitor.ts";
+import { FileScheduleRunStore, installScheduleRunLog, resolveRunLogConfig } from "../runLog.ts";
 
 declare module "@zerotal/core" {
   interface ContainerBindings {
@@ -18,13 +20,42 @@ export class SchedulerProvider extends ServiceProvider {
   static override environments: AppEnvironment[] = ["web", "console", "worker"];
 
   private _disposeObservability: (() => void) | undefined = undefined;
+  private _disposeRunLog: (() => void) | undefined = undefined;
 
   override onRegister(): void {
     // Convention-based auto-discovery of app/schedules. (Optional-chained so bare-container
     // unit tests with a minimal app stub don't need to stub registerConcern.)
     this.app.registerConcern?.(schedulesConcern);
 
+    // `zt doctor`: surface Schedule classes whose config is declared static —
+    // convention discovery warns at boot, but a boot log line scrolls away; the
+    // doctor holds the finding still.
+    this.app.registerDoctorCheck?.({
+      id: "schedule-static-config",
+      label: "Schedule config",
+      run: () => {
+        const manager = this.app.container.tryMake("scheduler") as SchedulerManager | undefined;
+        const findings = manager?.staticConfigFindings ?? [];
+        if (findings.length === 0) return { status: "ok", message: "instance properties" };
+        return {
+          status: "warn",
+          message:
+            findings.map((f) => `${f.className} declares static ${f.keys.join(", ")}`).join("; ") +
+            " — static schedule config registers nothing.",
+          fix: 'Drop the `static` keyword (e.g. `override cron = "0 3 * * *"`).',
+        };
+      },
+    });
+
     this.app.container.singleton("scheduler", () => new SchedulerManager());
+
+    // Durable run history (see runLog.ts). Registered as its own binding so an app
+    // can rebind `scheduler.runs` (e.g. onto Redis) without touching the scheduler.
+    // The factory reads config lazily — config is loaded by the time anything makes it.
+    this.app.container.singleton("scheduler.runs", () => {
+      const config = resolveRunLogConfig(this.app);
+      return new FileScheduleRunStore(resolve(process.cwd(), config.path), config.keep);
+    });
   }
 
   override async onBooting(): Promise<void> {
@@ -38,6 +69,7 @@ export class SchedulerProvider extends ServiceProvider {
 
   override async onBooted(): Promise<void> {
     this._disposeObservability = installSchedulerObservability(this.app);
+    this._disposeRunLog = installScheduleRunLog(this.app);
 
     // Wire the distributed lock for cross-process withoutOverlapping. Falls back to
     // the in-process guard when no LockProvider is registered.
@@ -48,6 +80,9 @@ export class SchedulerProvider extends ServiceProvider {
     runner.registerLazy("schedule:list", () =>
       import("../commands/ScheduleListCommand.ts").then((m) => m.ScheduleListCommand),
     );
+    runner.registerLazy("schedule:runs", () =>
+      import("../commands/ScheduleRunsCommand.ts").then((m) => m.ScheduleRunsCommand),
+    );
   }
 
   override async onStarted(): Promise<void> {
@@ -58,6 +93,8 @@ export class SchedulerProvider extends ServiceProvider {
   override async onStopped(): Promise<void> {
     this._disposeObservability?.();
     this._disposeObservability = undefined;
+    this._disposeRunLog?.();
+    this._disposeRunLog = undefined;
 
     const scheduler = this.app.container.tryMake("scheduler") as SchedulerManager | undefined;
     scheduler?.stop();

package/src/runLog.ts

@@ -0,0 +1,185 @@
+/**
+ * Durable schedule run history.
+ *
+ * A cron task that quietly stopped firing looks identical to one with nothing to
+ * do, and the in-memory `lastRunAt` on each task dies with the process — so
+ * "did the retention sweep run last night?" had no answer after a restart. Every
+ * run (success or failure) is appended to a capped JSONL file under `storage/`,
+ * the same storage-root convention the framework's own log trail uses: durable
+ * across restarts, no database dependency, greppable in an emergency.
+ *
+ * Reading it: `bun zt schedule:runs`, the monitor panel's scheduled-tasks
+ * section, or {@link ScheduleRunStore.recent} in code. Swap the store by
+ * rebinding `scheduler.runs` in the container.
+ */
+import { appendFileSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname } from "node:path";
+import { FrameworkEvents } from "@zerotal/core";
+import type { Application } from "@zerotal/core";
+import { TaskRan, TaskFailed } from "./events.ts";
+
+/** One completed execution of a scheduled task. */
+export interface ScheduleRunRecord {
+  /** Task name, as shown by `schedule:list`. */
+  name: string;
+  /** When the run started (ISO 8601). */
+  startedAt: string;
+  /** When the run finished (ISO 8601). */
+  finishedAt: string;
+  durationMs: number;
+  ok: boolean;
+  /** The thrown error's message, present only when `ok` is false. */
+  error?: string;
+}
+
+/** Where completed runs are recorded and read back. Rebind `scheduler.runs` to replace. */
+export interface ScheduleRunStore {
+  record(run: ScheduleRunRecord): void;
+  /** Most recent runs, newest first, optionally filtered to one task name. */
+  recent(limit?: number, name?: string): ScheduleRunRecord[];
+  /** The most recent run of one task, or undefined if none is on record. */
+  lastFor(name: string): ScheduleRunRecord | undefined;
+}
+
+// The binding is declared here, next to its type, so every consumer resolves it typed.
+declare module "@zerotal/core" {
+  interface ContainerBindings {
+    "scheduler.runs": ScheduleRunStore;
+  }
+}
+
+/** `scheduler.runLog` config (read from `config/scheduler.ts` when present). */
+export interface RunLogConfig {
+  /** Default: on, except under `APP_ENV=test` (mirroring the file log trail). */
+  enabled: boolean;
+  /** JSONL file path, relative to the app root. */
+  path: string;
+  /** Records kept after compaction; the file is compacted at 2× this. */
+  keep: number;
+}
+
+export const DEFAULT_RUN_LOG_PATH = "storage/framework/schedule-runs.jsonl";
+export const DEFAULT_RUN_LOG_KEEP = 500;
+
+/** Resolve `scheduler.runLog` config with defaults, tolerating an absent config binding. */
+export function resolveRunLogConfig(app: Application): RunLogConfig {
+  let raw: { enabled?: boolean; path?: string; keep?: number } = {};
+  try {
+    const config = app.container.makeSync("config") as { get(key: string): unknown };
+    raw = (config.get("scheduler.runLog") ?? {}) as typeof raw;
+  } catch {
+    /* config not resolvable — use the defaults */
+  }
+  return {
+    enabled: raw.enabled ?? Bun.env["APP_ENV"] !== "test",
+    path: raw.path ?? DEFAULT_RUN_LOG_PATH,
+    keep: Math.max(1, raw.keep ?? DEFAULT_RUN_LOG_KEEP),
+  };
+}
+
+/**
+ * JSONL-backed run store. Appends are synchronous — runs happen at cron cadence,
+ * not request cadence, and a record that survives a crash is the whole point.
+ */
+export class FileScheduleRunStore implements ScheduleRunStore {
+  constructor(
+    private readonly _path: string,
+    private readonly _keep: number = DEFAULT_RUN_LOG_KEEP,
+  ) {}
+
+  record(run: ScheduleRunRecord): void {
+    mkdirSync(dirname(this._path), { recursive: true });
+    // Read-before-append: the file is capped and appends happen at cron cadence,
+    // so the read is cheap — and it repairs a torn tail every time. A crash
+    // mid-append (this process or a sibling) leaves no trailing newline, and
+    // appending straight on would merge this record into the torn line and lose
+    // them both.
+    let text = "";
+    try {
+      text = readFileSync(this._path, "utf8");
+    } catch {
+      /* no file yet */
+    }
+    const prefix = text.length > 0 && !text.endsWith("\n") ? "\n" : "";
+    appendFileSync(this._path, prefix + JSON.stringify(run) + "\n");
+    // Compact at 2× the cap so the rewrite cost is amortised, not per-append.
+    if (FileScheduleRunStore._parse(text).length + 1 >= this._keep * 2) this._compact();
+  }
+
+  recent(limit = 50, name?: string): ScheduleRunRecord[] {
+    let runs = this._readAll();
+    if (name !== undefined) runs = runs.filter((r) => r.name === name);
+    return runs.slice(-Math.max(1, limit)).reverse();
+  }
+
+  lastFor(name: string): ScheduleRunRecord | undefined {
+    return this.recent(1, name)[0];
+  }
+
+  private _readAll(): ScheduleRunRecord[] {
+    let text: string;
+    try {
+      text = readFileSync(this._path, "utf8");
+    } catch {
+      return []; // no file yet
+    }
+    return FileScheduleRunStore._parse(text);
+  }
+
+  private static _parse(text: string): ScheduleRunRecord[] {
+    const runs: ScheduleRunRecord[] = [];
+    for (const line of text.split("\n")) {
+      if (!line.trim()) continue;
+      try {
+        runs.push(JSON.parse(line) as ScheduleRunRecord);
+      } catch {
+        /* a torn line (crash mid-append) is dropped, not fatal */
+      }
+    }
+    return runs;
+  }
+
+  private _compact(): void {
+    const keep = this._readAll().slice(-this._keep);
+    writeFileSync(this._path, keep.map((r) => JSON.stringify(r)).join("\n") + "\n");
+  }
+}
+
+/**
+ * Subscribe the run store to the scheduler's completion events. `TaskRan` fires on
+ * success and `TaskFailed` on a throw, so together they are exactly one record per
+ * completed execution (skips are deliberate non-runs and are not recorded). Returns
+ * a disposer, or undefined when the run log is disabled.
+ */
+export function installScheduleRunLog(app: Application): (() => void) | undefined {
+  const config = resolveRunLogConfig(app);
+  if (!config.enabled) return undefined;
+
+  const store = app.container.tryMake("scheduler.runs");
+  if (!store) return undefined; // no SchedulerProvider — nothing to subscribe
+  const toRecord = (name: string, durationMs: number, ok: boolean, error?: string) => {
+    const finished = Date.now();
+    const record: ScheduleRunRecord = {
+      name,
+      startedAt: new Date(finished - durationMs).toISOString(),
+      finishedAt: new Date(finished).toISOString(),
+      durationMs: Math.round(durationMs),
+      ok,
+      ...(error !== undefined ? { error } : {}),
+    };
+    try {
+      store.record(record);
+    } catch (err) {
+      // A full disk must not take the scheduler down with it.
+      console.warn(`[Zerotal scheduler] failed to record run of "${name}":`, err);
+    }
+  };
+
+  const unsubs = [
+    FrameworkEvents.on(TaskRan, (e) => toRecord(e.name, e.durationMs, e.ok)),
+    FrameworkEvents.on(TaskFailed, (e) => toRecord(e.name, e.durationMs, false, e.error)),
+  ];
+  return () => {
+    for (const unsub of unsubs) unsub();
+  };
+}