chainlesschain 0.163.4 → 0.163.6

package/src/lib/cowork-cron.js

@@ -39,6 +39,11 @@ import {
   writeFileSync,
 } from "node:fs";
 import { join } from "node:path";
+import {
+  nextCronTime as nextAgentCronTime,
+  normalizeTimeZone,
+  previousCronTime as previousAgentCronTime,
+} from "./agent-schedule-store.js";
 import { withFileLock } from "./with-file-lock.js";
 
 export const _deps = {
@@ -53,6 +58,33 @@ export const _deps = {
   runTask: null, // injected at runtime to avoid circular import
 };
 
+export const COWORK_SCHEDULER_UNKNOWN_LEASE_EXPIRES_AT =
+  "9999-12-31T23:59:59.999Z";
+
+function coworkSchedulerError(
+  code,
+  message,
+  { retryable = false, retryAt } = {},
+) {
+  const error = new Error(message);
+  error.code = code;
+  error.retryable = retryable;
+  if (retryAt !== undefined) error.retryAt = retryAt;
+  return error;
+}
+
+function normalizedDate(value, label) {
+  const date =
+    value instanceof Date ? new Date(value.getTime()) : new Date(value);
+  if (!Number.isFinite(date.getTime())) {
+    throw coworkSchedulerError(
+      "COWORK_SCHEDULER_TIME_INVALID",
+      `${label} must be a valid date`,
+    );
+  }
+  return date;
+}
+
 // ─── Cron parser ─────────────────────────────────────────────────────────────
 
 const FIELD_RANGES = [
@@ -64,6 +96,56 @@ const FIELD_RANGES = [
 ];
 
 const SECOND_RANGE = [0, 59];
+const CRON_TIME_ZONE_FORMATTERS = new Map();
+
+function timeZoneFormatter(timeZone) {
+  let formatter = CRON_TIME_ZONE_FORMATTERS.get(timeZone);
+  if (!formatter) {
+    formatter = new Intl.DateTimeFormat("en-US-u-ca-gregory-nu-latn", {
+      timeZone,
+      year: "numeric",
+      month: "2-digit",
+      day: "2-digit",
+      hour: "2-digit",
+      minute: "2-digit",
+      second: "2-digit",
+      hourCycle: "h23",
+    });
+    CRON_TIME_ZONE_FORMATTERS.set(timeZone, formatter);
+  }
+  return formatter;
+}
+
+function timeZoneParts(epochMs, timeZone) {
+  const values = {};
+  for (const part of timeZoneFormatter(timeZone).formatToParts(epochMs)) {
+    if (part.type !== "literal") values[part.type] = Number(part.value);
+  }
+  return {
+    year: values.year,
+    month: values.month,
+    day: values.day,
+    hour: values.hour,
+    minute: values.minute,
+    second: values.second,
+    dayOfWeek: new Date(
+      Date.UTC(values.year, values.month - 1, values.day),
+    ).getUTCDay(),
+  };
+}
+
+function cronDateParts(date, timeZone) {
+  if (timeZone) return timeZoneParts(date.getTime(), timeZone);
+  return {
+    year: date.getFullYear(),
+    month: date.getMonth() + 1,
+    day: date.getDate(),
+    hour: date.getHours(),
+    minute: date.getMinutes(),
+    second: date.getSeconds(),
+    dayOfWeek: date.getDay(),
+  };
+}
 
 /**
  * Non-standard alias → 5-field expression. Aliases never carry seconds.
@@ -155,7 +237,7 @@ export function parseCronField(field, [min, max]) {
  * @param {string} expr
  * @returns {((date: Date) => boolean) & { hasSeconds: boolean }}
  */
-export function parseCron(expr) {
+export function parseCron(expr, options = {}) {
   if (typeof expr !== "string") {
     throw new Error("cron expression must be a string");
   }
@@ -167,6 +249,9 @@ export function parseCron(expr) {
     );
   }
   const hasSeconds = parts.length === 6;
+  const timeZone = normalizeTimeZone(
+    typeof options === "string" ? options : options?.timeZone,
+  );
   let second = null;
   let minute, hour, dom, month, dow;
   if (hasSeconds) {
@@ -187,12 +272,15 @@ export function parseCron(expr) {
   const dowRestricted = dowField !== "*";
 
   function matches(date) {
-    const s = date.getSeconds();
-    const m = date.getMinutes();
-    const h = date.getHours();
-    const D = date.getDate();
-    const M = date.getMonth() + 1; // JS month is 0-based
-    const W = date.getDay();
+    const value = date instanceof Date ? date : new Date(date);
+    if (!Number.isFinite(value.getTime())) return false;
+    const civil = cronDateParts(value, timeZone);
+    const s = civil.second;
+    const m = civil.minute;
+    const h = civil.hour;
+    const D = civil.day;
+    const M = civil.month;
+    const W = civil.dayOfWeek;
     if (hasSeconds && !second.has(s)) return false;
     if (!minute.has(m)) return false;
     if (!hour.has(h)) return false;
@@ -206,6 +294,10 @@ export function parseCron(expr) {
     return true;
   }
   matches.hasSeconds = hasSeconds;
+  matches.timeZone = timeZone;
+  matches.fields = { second, minute, hour, dom, month, dow };
+  matches.domRestricted = domRestricted;
+  matches.dowRestricted = dowRestricted;
   return matches;
 }
 
@@ -219,15 +311,153 @@ export function hasSecondsResolution(expr) {
 }
 
 /** Validate a cron expression — returns null if valid, error string otherwise. */
-export function validateCron(expr) {
+export function validateCron(expr, options = {}) {
   try {
-    parseCron(expr);
+    parseCron(expr, options);
     return null;
   } catch (err) {
     return err.message;
   }
 }
 
+/** Return the next real instant for a Cowork 5/6-field cron. */
+export function nextCoworkCronTime(expr, fromMs, options = {}) {
+  const matcher = parseCron(expr, options);
+  const from = Number(fromMs);
+  if (!Number.isFinite(from)) throw new Error("cron start time is invalid");
+  const expanded = _expandExpr(expr);
+  const parts = expanded.split(/\s+/);
+  const minuteFields = matcher.hasSeconds ? parts.slice(1) : parts;
+  const minuteExpressions =
+    matcher.domRestricted && matcher.dowRestricted
+      ? [
+          [
+            minuteFields[0],
+            minuteFields[1],
+            minuteFields[2],
+            minuteFields[3],
+            "*",
+          ].join(" "),
+          [
+            minuteFields[0],
+            minuteFields[1],
+            "*",
+            minuteFields[3],
+            minuteFields[4],
+          ].join(" "),
+        ]
+      : [minuteFields.join(" ")];
+  const nextMinute = (after) => {
+    const candidates = minuteExpressions
+      .map((candidate) =>
+        nextAgentCronTime(candidate, after, { timeZone: matcher.timeZone }),
+      )
+      .filter((candidate) => candidate !== null);
+    return candidates.length > 0 ? Math.min(...candidates) : null;
+  };
+  if (!matcher.hasSeconds) return nextMinute(from);
+
+  const seconds = [...matcher.fields.second].sort((a, b) => a - b);
+  let minute = nextMinute(Math.floor(from / 60_000) * 60_000 - 60_000);
+  while (minute !== null) {
+    for (const second of seconds) {
+      const candidate = minute + second * 1_000;
+      if (candidate > from) return candidate;
+    }
+    minute = nextMinute(minute);
+  }
+  return null;
+}
+
+/**
+ * Select the latest due instant in `[firstMs, throughMs]`. Six-field schedules
+ * advance by matching civil minutes, not every elapsed second, so a long
+ * outage cannot turn an every-second schedule into millions of iterations.
+ */
+export function latestCoworkCronTime(expr, firstMs, throughMs, options = {}) {
+  const first = Number(firstMs);
+  const through = Number(throughMs);
+  if (!Number.isSafeInteger(first) || !Number.isSafeInteger(through)) {
+    throw new Error("cron catch-up bounds are invalid");
+  }
+  if (first > through) return null;
+  const matcher = parseCron(expr, options);
+  const seconds = matcher.hasSeconds
+    ? [...matcher.fields.second].sort((a, b) => b - a)
+    : [0];
+  const expanded = _expandExpr(expr);
+  const fields = expanded.split(/\s+/);
+  const minuteFields = matcher.hasSeconds ? fields.slice(1) : fields;
+  const minuteExpressions =
+    matcher.domRestricted && matcher.dowRestricted
+      ? [
+          [
+            minuteFields[0],
+            minuteFields[1],
+            minuteFields[2],
+            minuteFields[3],
+            "*",
+          ].join(" "),
+          [
+            minuteFields[0],
+            minuteFields[1],
+            "*",
+            minuteFields[3],
+            minuteFields[4],
+          ].join(" "),
+        ]
+      : [minuteFields.join(" ")];
+
+  const throughMinute = Math.floor(through / 60_000) * 60_000;
+  for (const second of seconds) {
+    const candidate = throughMinute + second * 1_000;
+    if (
+      candidate >= first &&
+      candidate <= through &&
+      matcher(new Date(candidate))
+    ) {
+      return candidate;
+    }
+  }
+
+  const previousMinute = Math.max(
+    ...minuteExpressions
+      .map((candidate) =>
+        previousAgentCronTime(candidate, throughMinute, {
+          timeZone: matcher.timeZone,
+        }),
+      )
+      .filter((candidate) => candidate !== null),
+  );
+  if (Number.isFinite(previousMinute)) {
+    for (const second of seconds) {
+      const candidate = previousMinute + second * 1_000;
+      if (candidate >= first && candidate <= through) return candidate;
+    }
+  }
+  return first;
+}
+
+function currentCoworkCronTime(schedule, at) {
+  const date = normalizedDate(at, "cowork cron observation time");
+  const matcher = parseCron(schedule.cron, { timeZone: schedule.timeZone });
+  if (!matcher(date)) return null;
+  const resolution = matcher.hasSeconds ? 1_000 : 60_000;
+  return Math.floor(date.getTime() / resolution) * resolution;
+}
+
+function initialCoworkCronNextAt(schedule, at) {
+  const current = currentCoworkCronTime(schedule, at);
+  if (current !== null) return current;
+  return nextCoworkCronTime(
+    schedule.cron,
+    normalizedDate(at, "now").getTime(),
+    {
+      timeZone: schedule.timeZone,
+    },
+  );
+}
+
 // ─── Persistence ─────────────────────────────────────────────────────────────
 
 function _scheduleFile(cwd) {
@@ -293,20 +523,26 @@ function _withScheduleLock(cwd, body) {
 
 /** Atomically replace the full schedule list under a fail-closed lock. */
 export function saveSchedules(cwd, schedules) {
-  return _withScheduleLock(cwd, () =>
-    _saveSchedulesUnlocked(cwd, schedules),
-  );
+  return _withScheduleLock(cwd, () => _saveSchedulesUnlocked(cwd, schedules));
 }
 
 // ─── CRUD ────────────────────────────────────────────────────────────────────
 
 export function addSchedule(cwd, input) {
-  const { cron, templateId = null, userMessage, files = [] } = input || {};
+  const {
+    cron,
+    timeZone = null,
+    templateId = null,
+    userMessage,
+    files = [],
+  } = input || {};
   if (!userMessage || typeof userMessage !== "string") {
     throw new Error("userMessage is required");
   }
-  const err = validateCron(cron);
+  const normalizedTimeZone = normalizeTimeZone(timeZone);
+  const err = validateCron(cron, { timeZone: normalizedTimeZone });
   if (err) throw new Error(`invalid cron: ${err}`);
+  const createdAt = _deps.now();
 
   // Serialize the read-modify-write across processes (cc+cc / cc+desktop share
   // the cowork dir) so concurrently-added schedules don't clobber each other.
@@ -315,11 +551,17 @@ export function addSchedule(cwd, input) {
     const entry = {
       id: `sch-${crypto.randomUUID().slice(0, 12)}`,
       cron: cron.trim(),
+      ...(normalizedTimeZone ? { timeZone: normalizedTimeZone } : {}),
       templateId,
       userMessage,
       files: Array.isArray(files) ? files : [],
       enabled: true,
-      createdAt: _deps.now().toISOString(),
+      createdAt: createdAt.toISOString(),
+      nextAt: initialCoworkCronNextAt(
+        { cron: cron.trim(), timeZone: normalizedTimeZone },
+        createdAt,
+      ),
+      missedRunPolicy: "collapse",
       lastRunAt: null,
       lastStatus: null,
     };
@@ -329,6 +571,73 @@ export function addSchedule(cwd, input) {
   });
 }
 
+/**
+ * Upgrade a legacy schedule to durable next-fire state. Upgrade never replays
+ * pre-upgrade history: a matching current window is retained, otherwise the
+ * first future occurrence becomes authoritative.
+ */
+export function ensureScheduleNextAt(cwd, id, at = _deps.now()) {
+  return _withScheduleLock(cwd, () => {
+    const schedules = loadSchedules(cwd, { failOnMalformed: true });
+    const schedule = schedules.find((entry) => entry.id === id);
+    if (!schedule) return null;
+    if (Object.hasOwn(schedule, "nextAt")) {
+      if (
+        schedule.nextAt === null ||
+        (typeof schedule.nextAt === "number" &&
+          Number.isSafeInteger(schedule.nextAt) &&
+          schedule.nextAt >= 0)
+      ) {
+        return schedule;
+      }
+      throw coworkSchedulerError(
+        "COWORK_SCHEDULER_CURSOR_INVALID",
+        `Cowork schedule nextAt is invalid: ${id}`,
+      );
+    }
+    const lastRunAt = Date.parse(schedule.lastRunAt || "");
+    const observedAt = normalizedDate(at, "cowork cron migration time");
+    schedule.nextAt = Number.isSafeInteger(lastRunAt)
+      ? nextCoworkCronTime(schedule.cron, lastRunAt, {
+          timeZone: schedule.timeZone,
+        })
+      : initialCoworkCronNextAt(schedule, observedAt);
+    schedule.missedRunPolicy = "collapse";
+    _saveSchedulesUnlocked(cwd, schedules);
+    return schedule;
+  });
+}
+
+/**
+ * CAS-advance one due schedule beyond `from`, collapsing any number of missed
+ * periods to the single occurrence that was just durably enqueued.
+ */
+export function advanceScheduleNextAt(
+  cwd,
+  id,
+  { expectedNextAt, from = _deps.now() } = {},
+) {
+  return _withScheduleLock(cwd, () => {
+    const schedules = loadSchedules(cwd, { failOnMalformed: true });
+    const schedule = schedules.find((entry) => entry.id === id);
+    if (!schedule) return null;
+    if (
+      typeof schedule.nextAt !== "number" ||
+      schedule.nextAt !== Number(expectedNextAt)
+    ) {
+      return schedule;
+    }
+    schedule.nextAt = nextCoworkCronTime(
+      schedule.cron,
+      normalizedDate(from, "cowork cron advance time").getTime(),
+      { timeZone: schedule.timeZone },
+    );
+    schedule.missedRunPolicy = "collapse";
+    _saveSchedulesUnlocked(cwd, schedules);
+    return schedule;
+  });
+}
+
 export function removeSchedule(cwd, id) {
   return _withScheduleLock(cwd, () => {
     const schedules = loadSchedules(cwd, { failOnMalformed: true });
@@ -345,7 +654,12 @@ export function setScheduleEnabled(cwd, id, enabled) {
     const schedules = loadSchedules(cwd, { failOnMalformed: true });
     const s = schedules.find((x) => x.id === id);
     if (!s) return false;
-    s.enabled = !!enabled;
+    const nextEnabled = !!enabled;
+    if (nextEnabled && !s.enabled) {
+      s.nextAt = initialCoworkCronNextAt(s, _deps.now());
+      s.missedRunPolicy = "collapse";
+    }
+    s.enabled = nextEnabled;
     _saveSchedulesUnlocked(cwd, schedules);
     return true;
   });
@@ -363,6 +677,191 @@ export function updateScheduleRunState(cwd, id, { lastRunAt, lastStatus }) {
   });
 }
 
+/** Return one schedule by id, or null when it does not exist. */
+export function getSchedule(cwd, id) {
+  if (typeof id !== "string" || id.length === 0) return null;
+  return (
+    loadSchedules(cwd, { failOnMalformed: true }).find(
+      (schedule) => schedule.id === id,
+    ) || null
+  );
+}
+
+/**
+ * Bind a scheduler-kernel occurrence before starting the Cowork task.
+ * The same JSONL lock used by the legacy driver closes both old-first and
+ * new-first claim races during migration.
+ */
+export function bindSchedulerScheduleFire(
+  cwd,
+  id,
+  { deliveryId, occurrenceId, snapshotDigest, attempt, at = _deps.now() } = {},
+) {
+  if (
+    typeof deliveryId !== "string" ||
+    typeof occurrenceId !== "string" ||
+    typeof snapshotDigest !== "string" ||
+    deliveryId.length === 0 ||
+    occurrenceId.length === 0 ||
+    snapshotDigest.length === 0 ||
+    !Number.isSafeInteger(attempt) ||
+    attempt < 1
+  ) {
+    throw coworkSchedulerError(
+      "COWORK_SCHEDULER_BINDING_INVALID",
+      "Cowork scheduler binding requires deliveryId, occurrenceId, snapshotDigest, and a positive attempt",
+    );
+  }
+  const now = normalizedDate(at, "cowork scheduler binding time");
+  const nowMs = now.getTime();
+  return _withScheduleLock(cwd, () => {
+    const schedules = loadSchedules(cwd, { failOnMalformed: true });
+    const schedule = schedules.find((entry) => entry.id === id);
+    if (!schedule) {
+      throw coworkSchedulerError(
+        "COWORK_SCHEDULER_SCHEDULE_NOT_FOUND",
+        `Cowork schedule does not exist: ${id}`,
+      );
+    }
+    const prior = schedule.schedulerExecution;
+    if (prior?.status === "running") {
+      throw coworkSchedulerError(
+        "COWORK_SCHEDULER_OUTCOME_UNKNOWN",
+        `Cowork schedule outcome is unknown: ${id}`,
+      );
+    }
+    if (
+      prior?.status === "succeeded" &&
+      prior.occurrenceId === occurrenceId &&
+      prior.snapshotDigest === snapshotDigest
+    ) {
+      return schedule;
+    }
+    // A legacy runner may have completed after the kernel enqueued this fire
+    // but before it acquired the JSONL lock. Its durable delivery id is
+    // terminal evidence for the same logical fire, so never overwrite it with
+    // a new scheduler claim.
+    if (schedule.lastDeliveryId === deliveryId) return schedule;
+
+    const active = schedule.activeDelivery;
+    const activeExpiresAt = Date.parse(active?.leaseExpiresAt || "");
+    if (active && Number.isFinite(activeExpiresAt) && activeExpiresAt > nowMs) {
+      throw coworkSchedulerError(
+        "COWORK_SCHEDULER_LEGACY_CLAIM_ACTIVE",
+        `Cowork schedule is already claimed: ${id}`,
+        { retryable: true, retryAt: activeExpiresAt },
+      );
+    }
+
+    const fence =
+      Math.max(
+        Number(schedule.deliveryFence) || 0,
+        Number(active?.fence) || 0,
+      ) + 1;
+    schedule.deliveryFence = fence;
+    schedule.activeDelivery = {
+      deliveryId,
+      ownerId: `scheduler:${occurrenceId}:${attempt}`,
+      fence,
+      claimedAt: now.toISOString(),
+      leaseExpiresAt: COWORK_SCHEDULER_UNKNOWN_LEASE_EXPIRES_AT,
+    };
+    schedule.schedulerExecution = {
+      deliveryId,
+      occurrenceId,
+      snapshotDigest,
+      attempt,
+      status: "running",
+      startedAt: now.toISOString(),
+    };
+    _saveSchedulesUnlocked(cwd, schedules);
+    return schedule;
+  });
+}
+
+/**
+ * Atomically settle scheduler evidence and the legacy Cowork delivery state.
+ * A known failure may keep a short legacy-visible fence until retryAt; an
+ * unknown outcome never calls this function and therefore remains fenced.
+ */
+export function completeSchedulerScheduleFire(
+  cwd,
+  id,
+  {
+    deliveryId,
+    occurrenceId,
+    snapshotDigest,
+    attempt,
+    outcome,
+    result = null,
+    error = null,
+    retryAt,
+    at = _deps.now(),
+  } = {},
+) {
+  if (!["succeeded", "failed"].includes(outcome)) {
+    throw coworkSchedulerError(
+      "COWORK_SCHEDULER_OUTCOME_INVALID",
+      "Cowork scheduler outcome must be succeeded or failed",
+    );
+  }
+  const now = normalizedDate(at, "cowork scheduler completion time");
+  const retryAtMs =
+    retryAt === undefined || retryAt === null ? null : Number(retryAt);
+  if (retryAtMs !== null && !Number.isSafeInteger(retryAtMs)) {
+    throw coworkSchedulerError(
+      "COWORK_SCHEDULER_RETRY_TIME_INVALID",
+      "Cowork scheduler retryAt must be a safe epoch millisecond",
+    );
+  }
+  return _withScheduleLock(cwd, () => {
+    const schedules = loadSchedules(cwd, { failOnMalformed: true });
+    const schedule = schedules.find((entry) => entry.id === id);
+    if (!schedule) {
+      throw coworkSchedulerError(
+        "COWORK_SCHEDULER_SCHEDULE_NOT_FOUND",
+        `Cowork schedule does not exist: ${id}`,
+      );
+    }
+    const evidence = schedule.schedulerExecution;
+    if (
+      !evidence ||
+      evidence.deliveryId !== deliveryId ||
+      evidence.occurrenceId !== occurrenceId ||
+      evidence.snapshotDigest !== snapshotDigest ||
+      evidence.attempt !== attempt ||
+      evidence.status !== "running"
+    ) {
+      throw coworkSchedulerError(
+        "COWORK_SCHEDULER_BINDING_MISMATCH",
+        `Cowork scheduler evidence does not match the active claim: ${id}`,
+      );
+    }
+
+    schedule.schedulerExecution = {
+      ...evidence,
+      status: outcome,
+      endedAt: now.toISOString(),
+      ...(outcome === "succeeded" ? { result } : { error }),
+    };
+    if (outcome === "succeeded") {
+      schedule.lastDeliveryId = deliveryId;
+      schedule.lastRunAt = now.toISOString();
+      schedule.lastStatus = result?.status || "completed";
+      schedule.activeDelivery = null;
+    } else if (retryAtMs !== null && retryAtMs > now.getTime()) {
+      schedule.activeDelivery = {
+        ...schedule.activeDelivery,
+        leaseExpiresAt: new Date(retryAtMs).toISOString(),
+      };
+    } else {
+      schedule.activeDelivery = null;
+    }
+    _saveSchedulesUnlocked(cwd, schedules);
+    return schedule;
+  });
+}
+
 /**
  * Claim one concrete cron fire before launching its side effect. The persisted
  * delivery id prevents two scheduler processes from running the same fire; an
@@ -559,14 +1058,12 @@ export class CoworkCronScheduler {
       if (!s.enabled) continue;
       let matcher;
       try {
-        matcher = parseCron(s.cron);
+        matcher = parseCron(s.cron, { timeZone: s.timeZone });
       } catch (err) {
         this._emit({ type: "invalid-cron", id: s.id, error: err.message });
         continue;
       }
-      const fireKey = `${s.id}:${
-        matcher.hasSeconds ? _secondKey(now) : _minuteKey(now)
-      }`;
+      const fireKey = coworkCronFireKey(s, now);
       if (this._firedKeys.has(fireKey)) continue;
       if (this._running.has(s.id)) continue;
       const isDue = matcher(now);
@@ -634,27 +1131,30 @@ export class CoworkCronScheduler {
       deliveryId: claim.deliveryId,
     });
 
-    const renewal = setInterval(() => {
-      try {
-        const renewed = renewScheduleFire(this.cwd, schedule.id, claim, {
-          leaseMs: this.leaseMs,
-        });
-        if (!renewed) {
+    const renewal = setInterval(
+      () => {
+        try {
+          const renewed = renewScheduleFire(this.cwd, schedule.id, claim, {
+            leaseMs: this.leaseMs,
+          });
+          if (!renewed) {
+            this._emit({
+              type: "schedule-lease-lost",
+              id: schedule.id,
+              deliveryId: claim.deliveryId,
+            });
+          }
+        } catch (err) {
           this._emit({
-            type: "schedule-lease-lost",
+            type: "schedule-lease-renewal-failed",
             id: schedule.id,
             deliveryId: claim.deliveryId,
+            error: err.message,
           });
         }
-      } catch (err) {
-        this._emit({
-          type: "schedule-lease-renewal-failed",
-          id: schedule.id,
-          deliveryId: claim.deliveryId,
-          error: err.message,
-        });
-      }
-    }, Math.max(1000, Math.floor(this.leaseMs / 3)));
+      },
+      Math.max(1000, Math.floor(this.leaseMs / 3)),
+    );
     renewal.unref?.();
 
     let result = null;
@@ -718,12 +1218,28 @@ export class CoworkCronScheduler {
   }
 }
 
-function _minuteKey(date) {
+export function coworkCronMinuteKey(date) {
   return `${date.getFullYear()}-${date.getMonth()}-${date.getDate()}-${date.getHours()}-${date.getMinutes()}`;
 }
 
-function _secondKey(date) {
-  return `${_minuteKey(date)}-${date.getSeconds()}`;
+export function coworkCronSecondKey(date) {
+  return `${coworkCronMinuteKey(date)}-${date.getSeconds()}`;
+}
+
+export function coworkCronFireKey(schedule, date) {
+  const matcher = parseCron(schedule.cron, { timeZone: schedule.timeZone });
+  // Keep the old host-local key while old and new CLIs may share this store.
+  // Zoned schedules need epoch identity so repeated DST wall times stay distinct.
+  if (!matcher.timeZone) {
+    const wallKey = matcher.hasSeconds
+      ? coworkCronSecondKey(date)
+      : coworkCronMinuteKey(date);
+    return `${schedule.id}:${wallKey}`;
+  }
+  const epoch = matcher.hasSeconds
+    ? Math.floor(date.getTime() / 1_000) * 1_000
+    : Math.floor(date.getTime() / 60_000) * 60_000;
+  return `${schedule.id}:${epoch}`;
 }
 
 // =====================================================================