feat(cron): add default stagger controls for scheduled jobs

src/cron/normalize.ts

@@ -1,3 +1,4 @@
+import type { CronJobCreate, CronJobPatch } from "./types.js";
 import { sanitizeAgentId } from "../routing/session-key.js";
 import { isRecord } from "../utils.js";
 import {
@@ -8,7 +9,7 @@ import {
 import { parseAbsoluteTimeMs } from "./parse.js";
 import { migrateLegacyCronPayload } from "./payload-migration.js";
 import { inferLegacyName } from "./service/normalize.js";
-import type { CronJobCreate, CronJobPatch } from "./types.js";
+import { normalizeCronStaggerMs, resolveDefaultCronStaggerMs } from "./stagger.js";
 
 type UnknownRecord = Record<string, unknown>;
 
@@ -61,6 +62,13 @@ function coerceSchedule(schedule: UnknownRecord) {
     delete next.atMs;
   }
 
+  const staggerMs = normalizeCronStaggerMs(schedule.staggerMs);
+  if (staggerMs !== undefined) {
+    next.staggerMs = staggerMs;
+  } else if ("staggerMs" in next) {
+    delete next.staggerMs;
+  }
+
   return next;
 }
 
@@ -420,6 +428,19 @@ export function normalizeCronJobInput(
     ) {
       next.deleteAfterRun = true;
     }
+    if ("schedule" in next && isRecord(next.schedule) && next.schedule.kind === "cron") {
+      const schedule = next.schedule as UnknownRecord;
+      const explicit = normalizeCronStaggerMs(schedule.staggerMs);
+      if (explicit !== undefined) {
+        schedule.staggerMs = explicit;
+      } else {
+        const expr = typeof schedule.expr === "string" ? schedule.expr : "";
+        const defaultStaggerMs = resolveDefaultCronStaggerMs(expr);
+        if (defaultStaggerMs !== undefined) {
+          schedule.staggerMs = defaultStaggerMs;
+        }
+      }
+    }
     const payload = isRecord(next.payload) ? next.payload : null;
     const payloadKind = payload && typeof payload.kind === "string" ? payload.kind : "";
     const sessionTarget = typeof next.sessionTarget === "string" ? next.sessionTarget : "";