chainlesschain 0.163.5 → 0.163.7

package/src/lib/agent-schedule-store.js

@@ -22,7 +22,7 @@
 import fs from "fs";
 import os from "os";
 import path from "path";
-import { randomUUID } from "crypto";
+import { createHash, randomUUID } from "crypto";
 import { isEntryExpired, effectiveFireAt } from "./schedule-planner.js";
 import { SUBAGENT_PERMISSION_MODES } from "./subagent-contract.js";
 import { parseGoalCondition } from "./goal-condition-engine.js";
@@ -30,6 +30,7 @@ import { normalizeActionClass } from "./unattended-action-policy.js";
 import { withFileLock } from "./with-file-lock.js";
 
 export const SCHEDULE_KINDS = Object.freeze(["wakeup", "cron", "monitor"]);
+export const AGENDA_SCHEDULER_MIGRATION_SCHEMA_VERSION = 1;
 
 /** A valid absolute-epoch-ms expiry, or null (never expires). */
 function normalizeExpiresAt(v) {
@@ -168,6 +169,87 @@ function hasLiveExecutionLease(entry, now) {
   return Number(entry.executionLease?.expiresAt) > Number(now);
 }
 
+function stableJsonValue(value) {
+  if (Array.isArray(value)) return value.map(stableJsonValue);
+  if (value && typeof value === "object") {
+    return Object.fromEntries(
+      Object.keys(value)
+        .sort()
+        .map((key) => [key, stableJsonValue(value[key])]),
+    );
+  }
+  return value;
+}
+
+function agendaMigrationSource(entry) {
+  const source = { ...entry };
+  delete source.executionLease;
+  delete source.schedulerExecution;
+  delete source.schedulerMigration;
+  delete source.firedAt;
+  delete source.lastRunAt;
+  delete source.runs;
+  delete source.nextAt;
+  delete source.lastCheckAt;
+  delete source.checks;
+  delete source.lastMtimeMs;
+  delete source.lastEventId;
+  delete source.lastAuthority;
+  delete source.status;
+  return source;
+}
+
+export function agendaMigrationSourceDigest(entry) {
+  return createHash("sha256")
+    .update("chainlesschain.agenda.scheduler-migration-source.v1\0", "utf8")
+    .update(
+      JSON.stringify(stableJsonValue(agendaMigrationSource(entry))),
+      "utf8",
+    )
+    .digest("hex");
+}
+
+export function agendaMigrationSourceSnapshot(entry) {
+  return stableJsonValue(agendaMigrationSource(entry));
+}
+
+function schedulerMigrationFence(entry, now) {
+  const migration = entry.schedulerMigration;
+  if (
+    migration?.schemaVersion !== AGENDA_SCHEDULER_MIGRATION_SCHEMA_VERSION ||
+    typeof migration.retirementToken !== "string" ||
+    migration.retirementToken.length === 0
+  ) {
+    return false;
+  }
+  return (
+    hasLiveExecutionLease(entry, now) &&
+    entry.executionLease?.owner ===
+      `scheduler-migration:${migration.retirementToken}`
+  );
+}
+
+function applySchedulerMigrationFence(entry, now) {
+  const token = entry.schedulerMigration?.retirementToken;
+  if (typeof token !== "string" || token.length === 0) return false;
+  entry.executionLease = {
+    owner: `scheduler-migration:${token}`,
+    claimedAt: now,
+    expiresAt: Number.MAX_SAFE_INTEGER,
+  };
+  return true;
+}
+
+function normalizeMigrationField(value, field) {
+  if (typeof value !== "string" || value.trim().length === 0) {
+    throw agendaStoreError(
+      "AGENDA_SCHEDULER_MIGRATION_INVALID",
+      `Agenda scheduler migration ${field} is required`,
+    );
+  }
+  return value.trim();
+}
+
 function agendaStoreError(code, message, { retryable = false, retryAt } = {}) {
   const error = new Error(message);
   error.code = code;
@@ -185,7 +267,9 @@ function applyScheduledAgentSuccess(entry, atMs) {
   if (entry.kind === "cron") {
     entry.lastRunAt = atMs;
     entry.runs = (entry.runs || 0) + 1;
-    const next = nextCronTime(entry.cron, atMs);
+    const next = nextCronTime(entry.cron, atMs, {
+      timeZone: entry.timeZone || null,
+    });
     if (next == null) entry.status = "exhausted";
     else entry.nextAt = next;
     return;
@@ -196,6 +280,51 @@ function applyScheduledAgentSuccess(entry, atMs) {
   );
 }
 
+function applyScheduledMonitorSuccess(entry, monitorCheck, atMs) {
+  if (
+    entry.kind !== "monitor" ||
+    !monitorCheck ||
+    typeof monitorCheck !== "object" ||
+    Array.isArray(monitorCheck) ||
+    typeof monitorCheck.matched !== "boolean"
+  ) {
+    throw agendaStoreError(
+      "AGENDA_SCHEDULER_MONITOR_RESULT_INVALID",
+      `Scheduler monitor result is invalid: ${entry.id}`,
+    );
+  }
+  const mtimeMs =
+    monitorCheck.mtimeMs === null || monitorCheck.mtimeMs === undefined
+      ? null
+      : Number(monitorCheck.mtimeMs);
+  if (mtimeMs !== null && (!Number.isFinite(mtimeMs) || mtimeMs < 0)) {
+    throw agendaStoreError(
+      "AGENDA_SCHEDULER_MONITOR_RESULT_INVALID",
+      `Scheduler monitor mtime is invalid: ${entry.id}`,
+    );
+  }
+  entry.checks = (entry.checks || 0) + 1;
+  entry.lastCheckAt = atMs;
+  if (mtimeMs !== null && entry.lastMtimeMs == null) {
+    entry.lastMtimeMs = mtimeMs;
+  }
+  if (monitorCheck.matched) {
+    entry.status = "matched";
+    entry.matchedAt = atMs;
+    if (monitorCheck.eventId != null) {
+      entry.lastEventId = String(monitorCheck.eventId);
+      entry.lastEventAt = atMs;
+    }
+    if (monitorCheck.authority != null) {
+      entry.lastAuthority = String(monitorCheck.authority);
+    }
+  } else if (entry.maxChecks != null && entry.checks >= entry.maxChecks) {
+    entry.status = "exhausted";
+  } else {
+    entry.nextAt = atMs + entry.intervalMs;
+  }
+}
+
 /** Statuses an entry can never leave — safe to prune. */
 export const TERMINAL_STATUSES = Object.freeze([
   "fired",
@@ -232,6 +361,61 @@ const CRON_RANGES = [
   [0, 6], // day of week (0/7 = Sunday)
 ];
 
+const CRON_TIME_ZONE_FORMATTERS = new Map();
+
+export function normalizeTimeZone(value) {
+  if (value == null || value === "") return null;
+  if (typeof value !== "string") {
+    throw new Error("cron timeZone must be an IANA time zone string");
+  }
+  const requested = value.trim();
+  if (!requested) return null;
+  if (requested.length > 128 || /\p{Cc}/u.test(requested)) {
+    throw new Error("invalid IANA time zone");
+  }
+  try {
+    return new Intl.DateTimeFormat("en-US", {
+      timeZone: requested,
+    }).resolvedOptions().timeZone;
+  } catch {
+    throw new Error(`invalid IANA time zone: ${requested}`);
+  }
+}
+
+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",
+      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,
+    minute: values.minute,
+    hour: values.hour,
+    day: values.day,
+    month: values.month,
+    dayOfWeek: new Date(
+      Date.UTC(values.year, values.month - 1, values.day),
+    ).getUTCDay(),
+  };
+}
+
 function parseCronField(field, [min, max]) {
   const values = new Set();
   for (const part of String(field).split(",")) {
@@ -280,13 +464,175 @@ function cronMatches(sets, date) {
   );
 }
 
+function timeZoneOffsetAt(epochMs, timeZone) {
+  const minuteEpoch = Math.floor(epochMs / 60_000) * 60_000;
+  const parts = timeZoneParts(minuteEpoch, timeZone);
+  return (
+    Date.UTC(parts.year, parts.month - 1, parts.day, parts.hour, parts.minute) -
+    minuteEpoch
+  );
+}
+
+function localDayOffsets(year, month, day, timeZone) {
+  const reference = Date.UTC(year, month - 1, day, 12, 0, 0);
+  return [
+    ...new Set(
+      [-36, -12, 0, 12, 36].map((hours) =>
+        timeZoneOffsetAt(reference + hours * 3_600_000, timeZone),
+      ),
+    ),
+  ];
+}
+
+function epochCandidatesForCivilMinute(
+  { year, month, day, hour, minute },
+  timeZone,
+  offsets,
+) {
+  const civilEpoch = Date.UTC(year, month - 1, day, hour, minute, 0);
+  const matches = [];
+  for (const offset of offsets) {
+    const epoch = civilEpoch - offset;
+    const actual = timeZoneParts(epoch, timeZone);
+    if (
+      actual.year === year &&
+      actual.month === month &&
+      actual.day === day &&
+      actual.hour === hour &&
+      actual.minute === minute
+    ) {
+      matches.push(epoch);
+    }
+  }
+  return [...new Set(matches)].sort((a, b) => a - b);
+}
+
+function nextCronTimeInTimeZone(sets, fromMs, timeZone) {
+  const from = Number(fromMs);
+  const firstLocal = timeZoneParts(from, timeZone);
+  const firstLocalDay = Date.UTC(
+    firstLocal.year,
+    firstLocal.month - 1,
+    firstLocal.day,
+  );
+  const minuteLimit = 366 * 24 * 60;
+  const lastEpoch = Math.floor(from / 60_000) * 60_000 + minuteLimit * 60_000;
+  const hours = [...sets[1]].sort((a, b) => a - b);
+  const minutes = [...sets[0]].sort((a, b) => a - b);
+  let earliest = null;
+
+  // Iterate civil dates instead of formatting every real minute. At most two
+  // UTC offsets can map a civil minute around a DST transition; verifying each
+  // reconstructed candidate preserves missing and repeated wall-time behavior.
+  // Start one civil day earlier because a rare midnight rollback can make a
+  // future real instant display as the previous local date. Once a later civil
+  // date is more than 36 hours beyond the best epoch, no supported IANA offset
+  // can map that date back before the current best candidate.
+  for (let dayOffset = -1; dayOffset <= 367; dayOffset += 1) {
+    const civilDay = firstLocalDay + dayOffset * 86_400_000;
+    if (earliest != null && civilDay - 36 * 3_600_000 > earliest) break;
+    const date = new Date(civilDay);
+    const year = date.getUTCFullYear();
+    const month = date.getUTCMonth() + 1;
+    const day = date.getUTCDate();
+    const dayOfWeek = date.getUTCDay();
+    if (
+      !sets[2].has(day) ||
+      !sets[3].has(month) ||
+      (!sets[4].has(dayOfWeek) && !(sets[4].has(7) && dayOfWeek === 0))
+    ) {
+      continue;
+    }
+    const offsets = localDayOffsets(year, month, day, timeZone);
+    for (const hour of hours) {
+      for (const minute of minutes) {
+        for (const epoch of epochCandidatesForCivilMinute(
+          { year, month, day, hour, minute },
+          timeZone,
+          offsets,
+        )) {
+          if (
+            epoch > from &&
+            epoch <= lastEpoch &&
+            (earliest == null || epoch < earliest)
+          ) {
+            earliest = epoch;
+          }
+        }
+      }
+    }
+  }
+  return earliest;
+}
+
+function previousCronTimeInTimeZone(sets, fromMs, timeZone) {
+  const from = Number(fromMs);
+  const firstLocal = timeZoneParts(from, timeZone);
+  const firstLocalDay = Date.UTC(
+    firstLocal.year,
+    firstLocal.month - 1,
+    firstLocal.day,
+  );
+  const minuteLimit = 366 * 24 * 60;
+  const firstEpoch = Math.floor(from / 60_000) * 60_000 - minuteLimit * 60_000;
+  const hours = [...sets[1]].sort((a, b) => b - a);
+  const minutes = [...sets[0]].sort((a, b) => b - a);
+  let latest = null;
+
+  // Start one civil day ahead because a rare midnight transition can make a
+  // prior real instant display as the following local date.
+  for (let dayOffset = 1; dayOffset >= -367; dayOffset -= 1) {
+    const civilDay = firstLocalDay + dayOffset * 86_400_000;
+    if (latest != null && civilDay + 36 * 3_600_000 < latest) break;
+    const date = new Date(civilDay);
+    const year = date.getUTCFullYear();
+    const month = date.getUTCMonth() + 1;
+    const day = date.getUTCDate();
+    const dayOfWeek = date.getUTCDay();
+    if (
+      !sets[2].has(day) ||
+      !sets[3].has(month) ||
+      (!sets[4].has(dayOfWeek) && !(sets[4].has(7) && dayOfWeek === 0))
+    ) {
+      continue;
+    }
+    const offsets = localDayOffsets(year, month, day, timeZone);
+    for (const hour of hours) {
+      for (const minute of minutes) {
+        for (const epoch of epochCandidatesForCivilMinute(
+          { year, month, day, hour, minute },
+          timeZone,
+          offsets,
+        )) {
+          if (
+            epoch < from &&
+            epoch >= firstEpoch &&
+            (latest == null || epoch > latest)
+          ) {
+            latest = epoch;
+          }
+        }
+      }
+    }
+  }
+  return latest;
+}
+
 /**
- * Next epoch-ms at which `expr` fires strictly after `fromMs` (local time,
- * minute granularity). Scans up to ~366 days then gives up (returns null) so a
- * never-matching expression can't loop forever.
+ * Next epoch-ms at which `expr` fires strictly after `fromMs`, at minute
+ * granularity. By default this preserves host-local cron behavior; an explicit
+ * IANA `timeZone` evaluates the same epoch minutes against that civil clock.
+ * A repeated fall-back wall minute therefore maps to both real instants, while
+ * a skipped spring-forward wall minute does not exist. Scans up to ~366 days
+ * then gives up (returns null) so a never-matching expression can't loop
+ * forever.
  */
-export function nextCronTime(expr, fromMs) {
+export function nextCronTime(expr, fromMs, options = {}) {
   const sets = parseCron(expr);
+  const timeZone = normalizeTimeZone(
+    typeof options === "string" ? options : options?.timeZone,
+  );
+  if (timeZone) return nextCronTimeInTimeZone(sets, fromMs, timeZone);
   const cursor = new Date(fromMs);
   cursor.setSeconds(0, 0);
   cursor.setMinutes(cursor.getMinutes() + 1);
@@ -298,6 +644,25 @@ export function nextCronTime(expr, fromMs) {
   return null;
 }
 
+/** Previous cron occurrence strictly before `fromMs`, bounded to one year. */
+export function previousCronTime(expr, fromMs, options = {}) {
+  const sets = parseCron(expr);
+  const timeZone = normalizeTimeZone(
+    typeof options === "string" ? options : options?.timeZone,
+  );
+  if (timeZone) return previousCronTimeInTimeZone(sets, fromMs, timeZone);
+  const cursor = new Date(fromMs);
+  cursor.setSeconds(0, 0);
+  if (cursor.getTime() >= Number(fromMs))
+    cursor.setMinutes(cursor.getMinutes() - 1);
+  const limit = 366 * 24 * 60;
+  for (let i = 0; i < limit; i += 1) {
+    if (cronMatches(sets, cursor)) return cursor.getTime();
+    cursor.setMinutes(cursor.getMinutes() - 1);
+  }
+  return null;
+}
+
 // ─── store ───────────────────────────────────────────────────────────────
 
 export class AgentScheduleStore {
@@ -390,12 +755,16 @@ export class AgentScheduleStore {
       expiresAt = null,
       expiresInMs = null,
       jitterMs = 0,
+      timeZone = null,
     } = options;
     if (!prompt || typeof prompt !== "string") {
       throw new Error("cron requires a prompt");
     }
     const now = this._now();
-    const nextAt = nextCronTime(cron, now); // validates the expression too
+    const normalizedTimeZone = normalizeTimeZone(timeZone);
+    const nextAt = nextCronTime(cron, now, {
+      timeZone: normalizedTimeZone,
+    }); // validates the expression and optional IANA time zone
     if (nextAt == null) {
       throw new Error(`cron "${cron}" has no upcoming match`);
     }
@@ -406,6 +775,7 @@ export class AgentScheduleStore {
       kind: "cron",
       prompt,
       cron,
+      ...(normalizedTimeZone ? { timeZone: normalizedTimeZone } : {}),
       label: label || null,
       nextAt,
       expiresAt: resolveExpiresAt(expiresAt, expiresInMs, now),
@@ -532,15 +902,246 @@ export class AgentScheduleStore {
     return this.list().find((entry) => entry.id === id) || null;
   }
 
+  prepareSchedulerMigration(
+    id,
+    { migrationId, sourceDigest, targetJobId } = {},
+  ) {
+    const migration = normalizeMigrationField(migrationId, "migrationId");
+    const expectedDigest = normalizeMigrationField(
+      sourceDigest,
+      "sourceDigest",
+    );
+    const target = normalizeMigrationField(targetJobId, "targetJobId");
+    this._ensureDir();
+    return withFileLock(
+      path.join(this.dir, ".agenda-claims"),
+      () => {
+        for (const kind of SCHEDULE_KINDS) {
+          const entries = this._readAll(kind);
+          const entry = entries.find((candidate) => candidate.id === id);
+          if (!entry) continue;
+          if (!isSchedulableStatus(entry)) {
+            throw agendaStoreError(
+              "AGENDA_SCHEDULER_ENTRY_TERMINAL",
+              `Agenda entry is not schedulable: ${id}`,
+            );
+          }
+          const actualDigest = agendaMigrationSourceDigest(entry);
+          if (actualDigest !== expectedDigest) {
+            throw agendaStoreError(
+              "AGENDA_SCHEDULER_MIGRATION_SOURCE_CHANGED",
+              `Agenda entry changed before migration: ${id}`,
+            );
+          }
+          const prior = entry.schedulerMigration;
+          if (prior) {
+            if (
+              prior.schemaVersion !==
+                AGENDA_SCHEDULER_MIGRATION_SCHEMA_VERSION ||
+              prior.sourceDigest !== expectedDigest ||
+              prior.targetJobId !== target ||
+              prior.migrationId !== migration ||
+              prior.state !== "prepared"
+            ) {
+              throw agendaStoreError(
+                "AGENDA_SCHEDULER_MIGRATION_CONFLICT",
+                `Agenda entry already belongs to another scheduler migration: ${id}`,
+              );
+            }
+            return entry;
+          }
+          entry.schedulerMigration = {
+            schemaVersion: AGENDA_SCHEDULER_MIGRATION_SCHEMA_VERSION,
+            state: "prepared",
+            migrationId: migration,
+            sourceDigest: expectedDigest,
+            targetJobId: target,
+            preparedAt: this._now(),
+          };
+          this._writeAll(kind, entries);
+          return entry;
+        }
+        throw agendaStoreError(
+          "AGENDA_SCHEDULER_ENTRY_NOT_FOUND",
+          `Agenda entry does not exist: ${id}`,
+        );
+      },
+      { failIfUnavailable: true },
+    );
+  }
+
+  retireForSchedulerMigration(
+    id,
+    {
+      migrationId,
+      sourceDigest,
+      targetJobId,
+      retirementToken,
+      atMs = null,
+    } = {},
+  ) {
+    const migration = normalizeMigrationField(migrationId, "migrationId");
+    const expectedDigest = normalizeMigrationField(
+      sourceDigest,
+      "sourceDigest",
+    );
+    const target = normalizeMigrationField(targetJobId, "targetJobId");
+    const token = normalizeMigrationField(retirementToken, "retirementToken");
+    const now = atMs != null ? Number(atMs) : this._now();
+    this._ensureDir();
+    return withFileLock(
+      path.join(this.dir, ".agenda-claims"),
+      () => {
+        for (const kind of SCHEDULE_KINDS) {
+          const entries = this._readAll(kind);
+          const entry = entries.find((candidate) => candidate.id === id);
+          if (!entry) continue;
+          const prior = entry.schedulerMigration;
+          if (
+            prior?.schemaVersion !==
+              AGENDA_SCHEDULER_MIGRATION_SCHEMA_VERSION ||
+            prior.sourceDigest !== expectedDigest ||
+            prior.targetJobId !== target ||
+            prior.migrationId !== migration ||
+            !["prepared", "retired"].includes(prior.state)
+          ) {
+            throw agendaStoreError(
+              "AGENDA_SCHEDULER_MIGRATION_CONFLICT",
+              `Agenda migration preparation changed before retirement: ${id}`,
+            );
+          }
+          if (prior.state === "retired") {
+            if (
+              prior.retirementToken !== token ||
+              !schedulerMigrationFence(entry, now)
+            ) {
+              throw agendaStoreError(
+                "AGENDA_SCHEDULER_MIGRATION_CONFLICT",
+                `Agenda migration retirement fence changed: ${id}`,
+              );
+            }
+            return entry;
+          }
+          if (agendaMigrationSourceDigest(entry) !== expectedDigest) {
+            throw agendaStoreError(
+              "AGENDA_SCHEDULER_MIGRATION_SOURCE_CHANGED",
+              `Agenda entry changed before retirement: ${id}`,
+            );
+          }
+          if (hasLiveExecutionLease(entry, now)) {
+            throw agendaStoreError(
+              "AGENDA_SCHEDULER_LEGACY_CLAIM_ACTIVE",
+              `Agenda entry is already claimed by a legacy runner: ${id}`,
+              {
+                retryable: true,
+                retryAt: Number(entry.executionLease.expiresAt),
+              },
+            );
+          }
+          entry.schedulerMigration = {
+            ...prior,
+            state: "retired",
+            retirementToken: token,
+            retiredAt: now,
+          };
+          applySchedulerMigrationFence(entry, now);
+          this._writeAll(kind, entries);
+          return entry;
+        }
+        throw agendaStoreError(
+          "AGENDA_SCHEDULER_ENTRY_NOT_FOUND",
+          `Agenda entry does not exist: ${id}`,
+        );
+      },
+      { failIfUnavailable: true },
+    );
+  }
+
+  restoreFromSchedulerMigration(
+    id,
+    { migrationId, sourceDigest, targetJobId, retirementToken } = {},
+  ) {
+    const migrationIdValue = normalizeMigrationField(
+      migrationId,
+      "migrationId",
+    );
+    const expectedDigest = normalizeMigrationField(
+      sourceDigest,
+      "sourceDigest",
+    );
+    const target = normalizeMigrationField(targetJobId, "targetJobId");
+    const token =
+      retirementToken === null || retirementToken === undefined
+        ? null
+        : normalizeMigrationField(retirementToken, "retirementToken");
+    this._ensureDir();
+    return withFileLock(
+      path.join(this.dir, ".agenda-claims"),
+      () => {
+        for (const kind of SCHEDULE_KINDS) {
+          const entries = this._readAll(kind);
+          const entry = entries.find((candidate) => candidate.id === id);
+          if (!entry) continue;
+          const migration = entry.schedulerMigration;
+          if (!migration) {
+            if (
+              agendaMigrationSourceDigest(entry) !== expectedDigest ||
+              String(entry.executionLease?.owner || "").startsWith(
+                "scheduler-migration:",
+              )
+            ) {
+              throw agendaStoreError(
+                "AGENDA_SCHEDULER_MIGRATION_CONFLICT",
+                `Agenda source changed after rollback restoration: ${id}`,
+              );
+            }
+            return entry;
+          }
+          if (
+            migration?.schemaVersion !==
+              AGENDA_SCHEDULER_MIGRATION_SCHEMA_VERSION ||
+            migration.sourceDigest !== expectedDigest ||
+            agendaMigrationSourceDigest(entry) !== expectedDigest ||
+            migration.targetJobId !== target ||
+            migration.migrationId !== migrationIdValue ||
+            !["prepared", "retired"].includes(migration.state) ||
+            (migration.state === "retired" &&
+              (migration.retirementToken !== token ||
+                entry.executionLease?.owner !== `scheduler-migration:${token}`))
+          ) {
+            throw agendaStoreError(
+              "AGENDA_SCHEDULER_MIGRATION_CONFLICT",
+              `Agenda migration fence changed before rollback: ${id}`,
+            );
+          }
+          delete entry.schedulerMigration;
+          if (migration.state === "retired") delete entry.executionLease;
+          this._writeAll(kind, entries);
+          return entry;
+        }
+        throw agendaStoreError(
+          "AGENDA_SCHEDULER_ENTRY_NOT_FOUND",
+          `Agenda entry does not exist: ${id}`,
+        );
+      },
+      { failIfUnavailable: true },
+    );
+  }
+
   /** Entries whose time has come (pending wakeup / active cron|monitor). */
-  due(kind = null, atMs = null) {
+  due(kind = null, atMs = null, { schedulerMigration = false } = {}) {
     const now = atMs != null ? atMs : this._now();
     return this.list(kind).filter((entry) => {
       // An entry past its expiry never fires — even if it is not yet retired
       // (defense-in-depth: retireExpired need not have run first).
       if (isEntryExpired(entry, now)) return false;
       if (!isSchedulableStatus(entry)) return false;
-      if (hasLiveExecutionLease(entry, now)) return false;
+      if (
+        hasLiveExecutionLease(entry, now) &&
+        !(schedulerMigration && schedulerMigrationFence(entry, now))
+      ) {
+        return false;
+      }
       // The effective fire time applies the entry's OWN deterministic jitter
       // (`entry.jitterMs`, default 0 → base fire time, byte-identical to the
       // prior `dueAt`/`nextAt` comparison). A jittered entry fires slightly
@@ -609,7 +1210,7 @@ export class AgentScheduleStore {
   }
 
   /**
-   * Bind a scheduler claim to the legacy Agenda entry before agent execution.
+   * Bind a scheduler claim to the legacy Agenda entry before execution.
    * The same lock used by legacy `claimDue()` prevents an old/new driver from
    * starting the entry concurrently during migration.
    */
@@ -640,7 +1241,7 @@ export class AgentScheduleStore {
     return withFileLock(
       path.join(this.dir, ".agenda-claims"),
       () => {
-        for (const kind of ["wakeup", "cron"]) {
+        for (const kind of SCHEDULE_KINDS) {
           const entries = this._readAll(kind);
           const entry = entries.find((candidate) => candidate.id === id);
           if (!entry) continue;
@@ -658,7 +1259,8 @@ export class AgentScheduleStore {
           ) {
             return entry;
           }
-          if (hasLiveExecutionLease(entry, now)) {
+          const migrationFence = schedulerMigrationFence(entry, now);
+          if (hasLiveExecutionLease(entry, now) && !migrationFence) {
             throw agendaStoreError(
               "AGENDA_SCHEDULER_LEGACY_CLAIM_ACTIVE",
               `Agenda entry is already claimed by a legacy runner: ${id}`,
@@ -678,7 +1280,8 @@ export class AgentScheduleStore {
           // Fence an older CLI that only understands the legacy claim field.
           // Terminal scheduler evidence clears this lease; an outcome-unknown
           // execution intentionally keeps it non-expiring until adjudicated so
-          // an old runner cannot duplicate an uncertain agent side effect.
+          // an old runner cannot duplicate an uncertain external observation or
+          // agent side effect.
           entry.executionLease = {
             owner: `scheduler:${occurrenceId}:${attempt}`,
             claimedAt: now,
@@ -697,10 +1300,10 @@ export class AgentScheduleStore {
   }
 
   /**
-   * Atomically publish scheduler evidence and the legacy wakeup/cron state.
-   * A successful cron advances exactly once in the same JSONL replacement that
-   * records terminal evidence; failures keep the entry schedulable for the
-   * scheduler kernel's bounded retry policy.
+   * Atomically publish scheduler evidence and the legacy Agenda state. A
+   * successful cron advances and a successful monitor records/re-arms exactly
+   * once in the same JSONL replacement that records terminal evidence;
+   * failures keep the entry schedulable for the kernel's bounded retry policy.
    */
   completeSchedulerExecution(
     id,
@@ -711,6 +1314,7 @@ export class AgentScheduleStore {
       outcome,
       result = null,
       error = null,
+      monitorCheck = null,
       atMs = null,
     } = {},
   ) {
@@ -725,7 +1329,7 @@ export class AgentScheduleStore {
     return withFileLock(
       path.join(this.dir, ".agenda-claims"),
       () => {
-        for (const kind of ["wakeup", "cron"]) {
+        for (const kind of SCHEDULE_KINDS) {
           const entries = this._readAll(kind);
           const entry = entries.find((candidate) => candidate.id === id);
           if (!entry) continue;
@@ -742,16 +1346,121 @@ export class AgentScheduleStore {
               `Agenda scheduler evidence does not match the active claim: ${id}`,
             );
           }
+          let storedResult = result;
           if (outcome === "succeeded") {
-            applyScheduledAgentSuccess(entry, now);
+            if (entry.kind === "monitor") {
+              applyScheduledMonitorSuccess(entry, monitorCheck, now);
+              storedResult =
+                result && typeof result === "object" && !Array.isArray(result)
+                  ? { ...result, status: entry.status }
+                  : result;
+            } else {
+              applyScheduledAgentSuccess(entry, now);
+            }
           }
           entry.schedulerExecution = {
             ...evidence,
             status: outcome,
             endedAt: now,
-            ...(outcome === "succeeded" ? { result } : { error }),
+            ...(outcome === "succeeded" ? { result: storedResult } : { error }),
+          };
+          delete entry.executionLease;
+          if (isSchedulableStatus(entry))
+            applySchedulerMigrationFence(entry, now);
+          this._writeAll(kind, entries);
+          return entry;
+        }
+        throw agendaStoreError(
+          "AGENDA_SCHEDULER_ENTRY_NOT_FOUND",
+          `Agenda entry does not exist: ${id}`,
+        );
+      },
+      { failIfUnavailable: true },
+    );
+  }
+
+  /**
+   * Resolve start-only scheduler evidence after an operator has verified the
+   * external outcome. This is intentionally separate from normal completion:
+   * it preserves the adjudication identity and can release the non-expiring
+   * legacy fence without pretending that a machine observed a terminal result.
+   */
+  adjudicateSchedulerExecution(
+    id,
+    {
+      occurrenceId,
+      snapshotDigest,
+      attempt,
+      decision,
+      requestId,
+      atMs = null,
+    } = {},
+  ) {
+    if (!["confirmed_applied", "confirmed_not_applied"].includes(decision)) {
+      throw agendaStoreError(
+        "AGENDA_SCHEDULER_ADJUDICATION_INVALID",
+        "Agenda scheduler adjudication decision is invalid",
+      );
+    }
+    const now = atMs != null ? Number(atMs) : this._now();
+    this._ensureDir();
+    return withFileLock(
+      path.join(this.dir, ".agenda-claims"),
+      () => {
+        for (const kind of SCHEDULE_KINDS) {
+          const entries = this._readAll(kind);
+          const entry = entries.find((candidate) => candidate.id === id);
+          if (!entry) continue;
+          const evidence = entry.schedulerExecution;
+          if (
+            evidence?.occurrenceId === occurrenceId &&
+            evidence.snapshotDigest === snapshotDigest &&
+            evidence.adjudication?.requestId === requestId &&
+            evidence.adjudication.decision === decision &&
+            evidence.status ===
+              (decision === "confirmed_applied"
+                ? "adjudicated_applied"
+                : "adjudicated_not_applied")
+          ) {
+            return entry;
+          }
+          if (
+            !evidence ||
+            evidence.occurrenceId !== occurrenceId ||
+            evidence.snapshotDigest !== snapshotDigest ||
+            !Number.isSafeInteger(evidence.attempt) ||
+            evidence.attempt < 1 ||
+            evidence.attempt > attempt ||
+            evidence.status !== "running"
+          ) {
+            throw agendaStoreError(
+              "AGENDA_SCHEDULER_ADJUDICATION_EVIDENCE_MISMATCH",
+              `Agenda scheduler adjudication evidence does not match: ${id}`,
+            );
+          }
+          if (decision === "confirmed_applied") {
+            if (entry.kind === "monitor") {
+              // A generic operator decision proves the prior check ran, but
+              // not whether its observation matched. Pause the monitor rather
+              // than inventing a domain result or rearming a duplicate check.
+              entry.status = "adjudicated";
+              entry.lastCheckAt = now;
+            } else {
+              applyScheduledAgentSuccess(entry, now);
+            }
+          }
+          entry.schedulerExecution = {
+            ...evidence,
+            status:
+              decision === "confirmed_applied"
+                ? "adjudicated_applied"
+                : "adjudicated_not_applied",
+            endedAt: now,
+            adjudication: { requestId, decision },
           };
           delete entry.executionLease;
+          if (isSchedulableStatus(entry))
+            applySchedulerMigrationFence(entry, now);
           this._writeAll(kind, entries);
           return entry;
         }
@@ -841,7 +1550,9 @@ export class AgentScheduleStore {
     return this._mutate("cron", id, (entry) => {
       entry.lastRunAt = now;
       entry.runs = (entry.runs || 0) + 1;
-      const next = nextCronTime(entry.cron, now);
+      const next = nextCronTime(entry.cron, now, {
+        timeZone: entry.timeZone || null,
+      });
       if (next == null) {
         entry.status = "exhausted";
       } else {
@@ -866,32 +1577,11 @@ export class AgentScheduleStore {
   ) {
     const now = atMs != null ? atMs : this._now();
     return this._mutate("monitor", id, (entry) => {
-      entry.checks = (entry.checks || 0) + 1;
-      entry.lastCheckAt = now;
-      // Record the mtime baseline the first time we see the file (for a
-      // watchChange monitor); leave it fixed thereafter so "changed" always
-      // means "changed since we started watching".
-      if (mtimeMs != null && entry.lastMtimeMs == null) {
-        entry.lastMtimeMs = mtimeMs;
-      }
-      if (matched) {
-        entry.status = "matched";
-        entry.matchedAt = now;
-        // Audit record of the firing: the deterministic monitor-event id + the
-        // (always SYSTEM/steer) authority the event was delivered under. Durable
-        // on the entry so `cc agenda list --json` and a future resident daemon
-        // can recognise / dedup the exact observation. Only stamped when the
-        // caller supplies them, so legacy callers stay byte-identical.
-        if (eventId != null) {
-          entry.lastEventId = String(eventId);
-          entry.lastEventAt = now;
-        }
-        if (authority != null) entry.lastAuthority = String(authority);
-      } else if (entry.maxChecks != null && entry.checks >= entry.maxChecks) {
-        entry.status = "exhausted";
-      } else {
-        entry.nextAt = now + entry.intervalMs;
-      }
+      applyScheduledMonitorSuccess(
+        entry,
+        { matched: Boolean(matched), mtimeMs, eventId, authority },
+        now,
+      );
     });
   }