fix(daemon+dashboard): cron UTC contract — stale test, perf fast path, dashboard duplicate

CHANGELOG.md

@@ -1521,6 +1521,74 @@ unnoticed because the hang-detector happened to rescue it.
   stay in sync with `start()`: a gap longer than the slow tier is itself the
   signal that the previous outage ended, and the next failure starts fresh.
 
+### Fixed — FM-8 cron tests still asserted the pre-#21 local-time contract
+
+PR #21 (`1e24108d`) deliberately moved cron-expression evaluation off the
+daemon's ambient timezone and into the cron's `timezone` field, defaulting to
+UTC. It updated the `nextFireFromCron` unit tests but missed the FM-8
+integration block in `tests/integration/phase5-failure-modes.test.ts`, which
+kept asserting the superseded contract — its comment still read *"The scheduler
+uses `Date.getHours()` (local wall clock)"*.
+
+The block only passed on a host whose local time was UTC: on the fleet host
+(EDT) `fixed-hour cron expression fires at the correct local hour` failed, and
+under `TZ=Pacific/Auckland` the weekday case failed too — it had been passing
+under EDT by coincidence, not because it was timezone-agnostic.
+
+- Rewritten against pinned absolute UTC instants (`Date.UTC`), so the tests
+  assert the real contract and pass identically on any host timezone —
+  verified green under `Pacific/Auckland` (UTC+12), `UTC`, and `Asia/Kolkata`
+  (UTC+5:30).
+- Added a declared-timezone case: `0 3 * * *` with
+  `timezone: "America/New_York"` must NOT fire at 03:00 UTC and must fire at
+  07:00 UTC (EDT). This is the half of #21's contract that had no
+  scheduler-level integration coverage — it proves `timezone` threads through
+  `CronScheduler`, not just `nextFireFromCron`.
+
+### Fixed — `nextFireFromCron` took a 27.6x-slower path for the default (UTC) timezone
+
+Since PR #21, every candidate minute in `nextFireFromCron`'s scan went through
+`Intl.DateTimeFormat.formatToParts()`, including for the default UTC timezone —
+correct, but needlessly expensive: `formatToParts` exists for genuine
+timezone-conversion, and UTC has no DST for it to be doing any real work on.
+A sparse expression (`0 0 31 1,2 *`) scans up to ~291K candidate minutes;
+measured 9,382ms for that scan via `formatToParts` vs 340ms via native `Date`
+UTC getters — enough to push a single next-fire computation past the daemon's
+own tick budget under load.
+
+Added a `utcFields()` fast path using `getUTCMinutes`/`getUTCHours`/etc.
+directly, taken only when `timezone === DEFAULT_CRON_TIMEZONE` (the exact
+default constant) — an equivalent spelling like `Etc/UTC` still goes through
+`Intl` and is unaffected, just not accelerated. Added an equivalence test
+(`UTC` vs `Etc/UTC` must agree on every candidate) and a timing regression
+guard so a future change can't silently regress this path back onto `Intl`.
+
+### Fixed — dashboard health endpoint ignored a cron's declared `timezone`
+
+`dashboard/src/app/api/workflows/health/route.ts` carried its own inline
+`nextFireFromCronExpr`, duplicated from (and drifted independently of)
+`dashboard/src/app/api/workflows/crons/route.ts` — both predating the
+`timezone` field PR #21 added to the daemon's own evaluator. Health's
+duplicate evaluated every cron expression against ambient local getters
+(`getHours`/`getDay`/etc.), so a cron declaring `timezone: "America/New_York"`
+showed its next-fire time in the *dashboard host's* local time, not the
+timezone the cron actually fires in — a silent mismatch between what the
+daemon does and what the health page reports.
+
+Removed health's inline duplicate and moved a `timezone`-aware
+`nextFireFromCronExpr` into the shared `dashboard/src/lib/cron-utils.ts`
+(matching the daemon's `nextFireFromCron` semantics: UTC by default, `Intl`-based
+for a declared IANA zone). `computeNextFire` now threads `cron.timezone`
+through. Added a cross-implementation test importing both the daemon's and the
+dashboard's evaluators and asserting agreement across every field, including
+EST/EDT and Asia/Tokyo.
+
+**Known gap, not addressed here:** `dashboard/src/app/api/workflows/crons/route.ts`
+still carries its own separate inline duplicate (also local-getter-based,
+also ignoring `cron.timezone`) — this fix only reached the health endpoint.
+Flagged for a follow-up to consolidate `crons/route.ts` onto the same shared
+`cron-utils.ts` function.
+
 ### Added — canonical branch protection on `main`
 
 `main` previously had zero branch protection (no required status checks, no

dashboard/src/app/api/workflows/health/route.ts

@@ -24,7 +24,7 @@ import fs from 'fs';
 import path from 'path';
 import { NextRequest } from 'next/server';
 import { CTX_ROOT, getAllAgents } from '@/lib/config';
-import { parseDurationMs } from '@/lib/cron-utils';
+import { parseDurationMs, nextFireFromCronExpr } from '@/lib/cron-utils';
 
 export const dynamic = 'force-dynamic';
 
@@ -42,6 +42,8 @@ interface CronDefinition {
   fire_count?: number;
   description?: string;
   fire_at?: string;
+  /** IANA zone a cron EXPRESSION is evaluated in; default UTC (mirrors CronDefinition). */
+  timezone?: string;
   metadata?: Record<string, unknown>;
 }
 
@@ -143,64 +145,20 @@ function readExecutionLog(agentName: string): CronExecutionLogEntry[] {
 // Next-fire computation (mirrors /api/workflows/crons logic)
 // ---------------------------------------------------------------------------
 
-function computeNextFire(schedule: string, lastFiredAt: string | undefined, now: number): string {
+function computeNextFire(schedule: string, lastFiredAt: string | undefined, now: number, timezone?: string): string {
   const referenceMs = lastFiredAt ? new Date(lastFiredAt).getTime() : now;
   const durationMs = parseDurationMs(schedule);
   if (!isNaN(durationMs)) {
     const next = referenceMs + durationMs;
     return new Date(next <= now ? now + durationMs : next).toISOString();
   }
-  const nextMs = nextFireFromCronExpr(schedule, now);
+  // Thread the cron's own timezone, matching the daemon's computeNextFireAt.
+  const nextMs = nextFireFromCronExpr(schedule, now, timezone || undefined);
   if (!isNaN(nextMs)) return new Date(nextMs).toISOString();
   return 'unknown';
 }
 
-function nextFireFromCronExpr(expr: string, fromMs: number): number {
-  const parts = expr.trim().split(/\s+/);
-  if (parts.length !== 5) return NaN;
-  const [minuteStr, hourStr, domStr, monthStr, dowStr] = parts;
-
-  function expand(field: string, min: number, max: number): number[] {
-    const result = new Set<number>();
-    for (const part of field.split(',')) {
-      if (part === '*') { for (let i = min; i <= max; i++) result.add(i); }
-      else if (part.startsWith('*/')) {
-        const step = parseInt(part.slice(2), 10);
-        if (isNaN(step) || step <= 0) throw new Error('bad step');
-        for (let i = min; i <= max; i += step) result.add(i);
-      } else if (part.includes('-')) {
-        const [lo, hi] = part.split('-').map(s => parseInt(s, 10));
-        if (isNaN(lo) || isNaN(hi) || lo > hi) throw new Error('bad range');
-        for (let i = lo; i <= hi; i++) result.add(i);
-      } else {
-        const n = parseInt(part, 10);
-        if (isNaN(n)) throw new Error('bad value');
-        result.add(n);
-      }
-    }
-    return [...result].sort((a, b) => a - b);
-  }
 
-  let minutes: number[], hours: number[], doms: number[], months: number[], dows: number[];
-  try {
-    minutes = expand(minuteStr, 0, 59);
-    hours   = expand(hourStr, 0, 23);
-    doms    = expand(domStr, 1, 31);
-    months  = expand(monthStr, 1, 12);
-    dows    = expand(dowStr, 0, 6);
-  } catch { return NaN; }
-
-  const startMs = Math.floor(fromMs / 60_000) * 60_000 + 60_000;
-  let candidate = startMs;
-  for (let i = 0; i < 366 * 24 * 60; i++) {
-    const d = new Date(candidate);
-    if (months.includes(d.getMonth() + 1) && doms.includes(d.getDate()) &&
-        dows.includes(d.getDay()) && hours.includes(d.getHours()) &&
-        minutes.includes(d.getMinutes())) return candidate;
-    candidate += 60_000;
-  }
-  return NaN;
-}
 
 // ---------------------------------------------------------------------------
 // Health computation (pure, mirrors src/utils/cron-health.ts)
@@ -305,7 +263,7 @@ export async function GET(request: NextRequest) {
           e => e.cron === cron.name && new Date(e.ts).getTime() >= cutoff24h
         );
 
-        const nextFire = computeNextFire(cron.schedule, cron.last_fired_at, nowMs);
+        const nextFire = computeNextFire(cron.schedule, cron.last_fired_at, nowMs, cron.timezone);
 
         healthRows.push(computeHealth(
           agent.name,

dashboard/src/lib/cron-utils.ts

@@ -179,3 +179,152 @@ export function formatRelative(isoTs: string | null | undefined): string {
 
   return past ? `${label} ago` : `in ${label}`;
 }
+
+// ---------------------------------------------------------------------------
+// 5-field cron expression evaluator
+//
+// Mirrors src/daemon/cron-scheduler.ts's nextFireFromCron. It lives here rather
+// than being imported because the dashboard is a separate Next.js app that
+// cannot pull in daemon-side modules — the duplication this file's header
+// warns about. It previously existed as TWO inline copies (crons/route.ts and
+// health/route.ts), both of which matched cron fields with LOCAL Date getters
+// (getHours/getDate/getDay). PR #21 (1e24108d) fixed exactly that bug in the
+// daemon — moving evaluation to the cron's `timezone`, default UTC — but only
+// on the daemon side.
+//
+// The result was a live divergence: the daemon fired "0 9 * * *" at 09:00 UTC
+// while the dashboard displayed its next fire as 09:00 LOCAL (13:00 UTC on the
+// EDT fleet host), a 4-5h lie in the UI, and `cron.timezone` was ignored
+// outright. Consolidated to one implementation with the daemon's semantics.
+// ---------------------------------------------------------------------------
+
+const DEFAULT_CRON_TIMEZONE = 'UTC';
+
+const WEEKDAY_ABBR_TO_NUM: Record<string, number> = {
+  Sun: 0, Mon: 1, Tue: 2, Wed: 3, Thu: 4, Fri: 5, Sat: 6,
+};
+
+interface CronFields { minute: number; hour: number; day: number; month: number; weekday: number }
+
+function expandCronField(field: string, min: number, max: number): number[] {
+  const result = new Set<number>();
+  for (const part of field.split(',')) {
+    if (part === '*') {
+      for (let i = min; i <= max; i++) result.add(i);
+    } else if (part.startsWith('*/')) {
+      const step = parseInt(part.slice(2), 10);
+      if (isNaN(step) || step <= 0) throw new Error(`Invalid step: ${part}`);
+      for (let i = min; i <= max; i += step) result.add(i);
+    } else if (part.includes('-')) {
+      const [lo, hi] = part.split('-').map(s => parseInt(s, 10));
+      if (isNaN(lo) || isNaN(hi) || lo > hi) throw new Error(`Invalid range: ${part}`);
+      for (let i = lo; i <= hi; i++) result.add(i);
+    } else {
+      const n = parseInt(part, 10);
+      if (isNaN(n)) throw new Error(`Invalid value: ${part}`);
+      result.add(n);
+    }
+  }
+  return [...result].sort((a, b) => a - b);
+}
+
+/**
+ * UTC fast path — native getters instead of Intl. Semantically identical (UTC
+ * has no DST) but measured ~27x cheaper across the minute-by-minute scan below,
+ * which is what made the dashboard's /crons endpoint the slowest route it
+ * serves. UTC is the default, so this is the path nearly every cron takes.
+ */
+function utcCronFields(ms: number): CronFields {
+  const d = new Date(ms);
+  return {
+    minute: d.getUTCMinutes(),
+    hour: d.getUTCHours(),
+    day: d.getUTCDate(),
+    month: d.getUTCMonth() + 1, // getUTCMonth is 0-11; cron months are 1-12
+    weekday: d.getUTCDay(),
+  };
+}
+
+/**
+ * Next fire time (epoch ms) for a 5-field cron expression, strictly after
+ * `fromMs`, or NaN if the expression is unparseable or can never match.
+ *
+ * @param timezone IANA zone the expression's fields are evaluated in.
+ *                 Defaults to UTC — never the ambient timezone of whatever
+ *                 process renders the dashboard.
+ */
+export function nextFireFromCronExpr(
+  expr: string,
+  fromMs: number,
+  timezone: string = DEFAULT_CRON_TIMEZONE,
+): number {
+  const parts = expr.trim().split(/\s+/);
+  if (parts.length !== 5) return NaN;
+  const [minuteStr, hourStr, domStr, monthStr, dowStr] = parts;
+
+  let minutes: number[], hours: number[], doms: number[], months: number[], dows: number[];
+  try {
+    minutes = expandCronField(minuteStr, 0, 59);
+    hours   = expandCronField(hourStr,   0, 23);
+    doms    = expandCronField(domStr,    1, 31);
+    months  = expandCronField(monthStr,  1, 12);
+    dows    = expandCronField(dowStr,    0, 6);
+  } catch {
+    return NaN;
+  }
+
+  // Feasibility pre-check: a dom+month pair that exists in NO month (Feb 31)
+  // parses fine but can never match, and would otherwise walk the entire
+  // 1-year window just to return NaN. Feb counts as 29 — "29 2" is feasible in
+  // leap years, and whether the next one is inside the window is the scan's
+  // question, not this check's.
+  const MAX_DOM_BY_MONTH = [31, 29, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31];
+  if (!months.some((mo) => doms.some((d) => d <= MAX_DOM_BY_MONTH[mo - 1]))) {
+    return NaN;
+  }
+
+  let fieldsAt: (ms: number) => CronFields;
+  if (timezone === DEFAULT_CRON_TIMEZONE) {
+    fieldsAt = utcCronFields;
+  } else {
+    let formatter: Intl.DateTimeFormat;
+    try {
+      formatter = new Intl.DateTimeFormat('en-US', {
+        timeZone: timezone,
+        year: 'numeric', month: '2-digit', day: '2-digit',
+        hour: '2-digit', minute: '2-digit',
+        hourCycle: 'h23', weekday: 'short',
+      });
+    } catch {
+      return NaN; // invalid IANA string fails safe, as on the daemon side
+    }
+    fieldsAt = (ms) => {
+      const map: Record<string, string> = {};
+      for (const p of formatter.formatToParts(new Date(ms))) map[p.type] = p.value;
+      return {
+        minute: parseInt(map.minute, 10),
+        hour: parseInt(map.hour, 10),
+        day: parseInt(map.day, 10),
+        month: parseInt(map.month, 10),
+        weekday: WEEKDAY_ABBR_TO_NUM[map.weekday],
+      };
+    };
+  }
+
+  let candidate = Math.floor(fromMs / 60_000) * 60_000 + 60_000;
+  const MAX_MINUTES = 366 * 24 * 60;
+  for (let i = 0; i < MAX_MINUTES; i++) {
+    const f = fieldsAt(candidate);
+    if (
+      months.includes(f.month) &&
+      doms.includes(f.day) &&
+      dows.includes(f.weekday) &&
+      hours.includes(f.hour) &&
+      minutes.includes(f.minute)
+    ) {
+      return candidate;
+    }
+    candidate += 60_000;
+  }
+  return NaN;
+}