chainlesschain 0.163.5 → 0.163.7

package/src/lib/scheduler-kernel/agenda-adapter.js

@@ -1,5 +1,12 @@
 import { createHash } from "node:crypto";
 import { effectiveFireAt } from "../schedule-planner.js";
+import {
+  agendaMigrationSourceDigest,
+  agendaMigrationSourceSnapshot,
+  nextCronTime,
+  normalizeTimeZone,
+  parseCron,
+} from "../agent-schedule-store.js";
 import {
   SchedulerKernelError,
   canonicalJson,
@@ -8,10 +15,21 @@ import {
   normalizeJson,
 } from "./contract.js";
 import { SchedulerRuntime } from "./runtime.js";
+import { schedulerMigrationSourceDigest } from "./store.js";
+import {
+  bindSchedulerAuthorityPolicy,
+  createSchedulerAuthorityResolver,
+} from "./authority-resolver.js";
+import { canonicalSchedulerSourcePath } from "./source-locator-path.js";
 
 export const AGENDA_SCHEDULER_KIND = "agenda";
 export const AGENDA_SCHEDULER_CAPABILITY = "agent.execute";
-export const AGENDA_SCHEDULER_ENTRY_KINDS = Object.freeze(["wakeup", "cron"]);
+export const AGENDA_SCHEDULER_MONITOR_CAPABILITY = "monitor.observe";
+export const AGENDA_SCHEDULER_ENTRY_KINDS = Object.freeze([
+  "wakeup",
+  "cron",
+  "monitor",
+]);
 export const AGENDA_SCHEDULER_RETRY_DELAY_MS = 60_000;
 
 function agendaError(
@@ -45,6 +63,125 @@ function safeFailure(error) {
   };
 }
 
+function capabilityForEntry(entry) {
+  return entry?.kind === "monitor"
+    ? AGENDA_SCHEDULER_MONITOR_CAPABILITY
+    : AGENDA_SCHEDULER_CAPABILITY;
+}
+
+function normalizeMonitorObservation(entry, observation) {
+  if (
+    !observation ||
+    typeof observation !== "object" ||
+    Array.isArray(observation) ||
+    typeof observation.matched !== "boolean"
+  ) {
+    throw agendaError(
+      "AGENDA_SCHEDULER_MONITOR_RESULT_INVALID",
+      `Agenda monitor returned an invalid observation: ${entry.id}`,
+    );
+  }
+  const mtimeMs =
+    observation.mtimeMs === null || observation.mtimeMs === undefined
+      ? null
+      : Number(observation.mtimeMs);
+  if (mtimeMs !== null && (!Number.isFinite(mtimeMs) || mtimeMs < 0)) {
+    throw agendaError(
+      "AGENDA_SCHEDULER_MONITOR_RESULT_INVALID",
+      `Agenda monitor returned an invalid mtime: ${entry.id}`,
+    );
+  }
+  const eventId = observation.matched
+    ? normalizeIdentifier(observation.eventId, "agenda.monitor.eventId")
+    : null;
+  const authority = observation.matched
+    ? normalizeIdentifier(observation.authority, "agenda.monitor.authority")
+    : null;
+  const duplicate = observation.matched && entry.lastEventId === eventId;
+  const notification =
+    observation.notification &&
+    typeof observation.notification === "object" &&
+    !Array.isArray(observation.notification)
+      ? {
+          title: String(observation.notification.title || ""),
+          body: String(observation.notification.body || ""),
+          level: String(observation.notification.level || "success"),
+        }
+      : null;
+  return {
+    matched: observation.matched,
+    mtimeMs,
+    eventId,
+    authority,
+    duplicate,
+    truncated: observation.truncated === true,
+    notification,
+  };
+}
+
+function validateMonitorSnapshot(snapshot) {
+  if (
+    !Number.isSafeInteger(snapshot.intervalMs) ||
+    snapshot.intervalMs < 1_000
+  ) {
+    throw agendaError(
+      "AGENDA_SCHEDULER_ENTRY_INVALID",
+      `Agenda monitor interval is invalid: ${snapshot.id}`,
+    );
+  }
+  if (!Number.isSafeInteger(snapshot.checks) || snapshot.checks < 0) {
+    throw agendaError(
+      "AGENDA_SCHEDULER_ENTRY_INVALID",
+      `Agenda monitor check count is invalid: ${snapshot.id}`,
+    );
+  }
+  if (!["command", "file", "http"].includes(snapshot.source)) {
+    throw agendaError(
+      "AGENDA_SCHEDULER_ENTRY_INVALID",
+      `Agenda monitor source is invalid: ${snapshot.id}`,
+    );
+  }
+  const sourceValue =
+    snapshot.source === "command"
+      ? snapshot.command
+      : snapshot.source === "file"
+        ? snapshot.watchFile
+        : snapshot.watchUrl;
+  if (typeof sourceValue !== "string" || sourceValue.length === 0) {
+    throw agendaError(
+      "AGENDA_SCHEDULER_ENTRY_INVALID",
+      `Agenda monitor source target is missing: ${snapshot.id}`,
+    );
+  }
+  if (
+    snapshot.watchChange === true &&
+    (snapshot.source !== "file" || snapshot.stopWhen != null)
+  ) {
+    throw agendaError(
+      "AGENDA_SCHEDULER_ENTRY_INVALID",
+      `Agenda monitor change condition is invalid: ${snapshot.id}`,
+    );
+  }
+  if (snapshot.stopWhen != null) {
+    if (typeof snapshot.stopWhen !== "string") {
+      throw agendaError(
+        "AGENDA_SCHEDULER_ENTRY_INVALID",
+        `Agenda monitor stop condition is invalid: ${snapshot.id}`,
+      );
+    }
+    try {
+      new RegExp(snapshot.stopWhen);
+    } catch (error) {
+      throw agendaError(
+        "AGENDA_SCHEDULER_ENTRY_INVALID",
+        `Agenda monitor stop condition is invalid: ${snapshot.id}`,
+        undefined,
+        error,
+      );
+    }
+  }
+}
+
 function validateEntrySnapshot(entry) {
   if (!entry || typeof entry !== "object" || Array.isArray(entry)) {
     throw agendaError(
@@ -55,6 +192,7 @@ function validateEntrySnapshot(entry) {
   const plain = { ...entry };
   delete plain.executionLease;
   delete plain.schedulerExecution;
+  delete plain.schedulerMigration;
   const snapshot = normalizeJson(plain, "agendaEntrySnapshot");
   snapshot.id = normalizeIdentifier(snapshot.id, "agenda.entry.id");
   if (!AGENDA_SCHEDULER_ENTRY_KINDS.includes(snapshot.kind)) {
@@ -63,21 +201,48 @@ function validateEntrySnapshot(entry) {
       `Agenda scheduler does not support entry kind: ${snapshot.kind}`,
     );
   }
-  if (typeof snapshot.prompt !== "string" || snapshot.prompt.length === 0) {
+  if (
+    snapshot.kind !== "monitor" &&
+    (typeof snapshot.prompt !== "string" || snapshot.prompt.length === 0)
+  ) {
     throw agendaError(
       "AGENDA_SCHEDULER_ENTRY_INVALID",
       `Agenda prompt is missing: ${snapshot.id}`,
     );
   }
+  if (snapshot.kind === "cron") {
+    try {
+      parseCron(snapshot.cron);
+      if (snapshot.timeZone != null) {
+        const timeZone = normalizeTimeZone(snapshot.timeZone);
+        if (!timeZone) throw new Error("cron timeZone must not be empty");
+        const nextAt = Number(snapshot.nextAt);
+        if (
+          nextCronTime(snapshot.cron, nextAt - 60_000, { timeZone }) !== nextAt
+        ) {
+          throw new Error("cron nextAt does not match its time zone");
+        }
+      }
+    } catch (error) {
+      throw agendaError(
+        "AGENDA_SCHEDULER_CRON_INVALID",
+        `Agenda cron definition is invalid: ${snapshot.id}`,
+        undefined,
+        error,
+      );
+    }
+  }
   const schedulable =
     (snapshot.kind === "wakeup" && snapshot.status === "pending") ||
-    (snapshot.kind === "cron" && snapshot.status === "active");
+    (["cron", "monitor"].includes(snapshot.kind) &&
+      snapshot.status === "active");
   if (!schedulable) {
     throw agendaError(
       "AGENDA_SCHEDULER_ENTRY_TERMINAL",
       `Agenda entry is not schedulable: ${snapshot.id}`,
     );
   }
+  if (snapshot.kind === "monitor") validateMonitorSnapshot(snapshot);
   normalizeEpochMs(Number(snapshot.createdAt), "agenda.entry.createdAt");
   const fireAt = effectiveFireAt(snapshot);
   if (fireAt == null) {
@@ -117,7 +282,14 @@ export function buildAgendaSchedulerJob(entry) {
       source: "agent-schedule-store",
       scheduleKind: snapshot.kind,
       expression:
-        snapshot.kind === "cron" ? snapshot.cron : String(snapshot.dueAt),
+        snapshot.kind === "cron"
+          ? snapshot.cron
+          : snapshot.kind === "monitor"
+            ? `every:${snapshot.intervalMs}`
+            : String(snapshot.dueAt),
+      ...(snapshot.kind === "cron" && snapshot.timeZone
+        ? { timeZone: snapshot.timeZone }
+        : {}),
     },
     payload: {
       entry: snapshot,
@@ -128,7 +300,7 @@ export function buildAgendaSchedulerJob(entry) {
       principal: { type: "agenda", id: snapshot.id },
       tenantId: null,
       workspaceId: null,
-      requestedCapabilities: [AGENDA_SCHEDULER_CAPABILITY],
+      requestedCapabilities: [capabilityForEntry(snapshot)],
       authorizationRefs: {
         decisionId: null,
         policyRevision: null,
@@ -163,6 +335,10 @@ function sameJob(current, desired) {
 
 export function syncAgendaSchedulerJob(schedulerStore, entry) {
   const desired = buildAgendaSchedulerJob(entry);
+  desired.authority = bindSchedulerAuthorityPolicy(
+    schedulerStore,
+    desired.authority,
+  );
   let current = schedulerStore.getJob(desired.id);
   if (!current) {
     try {
@@ -190,6 +366,223 @@ export function syncAgendaSchedulerJob(schedulerStore, entry) {
   }
 }
 
+export function migrateAgendaSchedulerEntry({
+  agendaStore,
+  schedulerStore,
+  entry,
+}) {
+  const snapshot = agendaEntrySnapshot(entry);
+  const directory = canonicalSchedulerSourcePath(agendaStore.dir);
+  const sourceScope = { store: "agent-schedule", directory };
+  const sourceLocator = {
+    schemaVersion: 1,
+    type: "agenda-store",
+    directory,
+  };
+  let prepared = schedulerStore.getActiveDomainMigrationBySource({
+    domain: "agenda",
+    sourceScope,
+    sourceId: snapshot.id,
+  });
+  if (!prepared && agendaStore.dir !== directory) {
+    const ambiguousLegacy = schedulerStore.getActiveDomainMigrationBySource({
+      domain: "agenda",
+      sourceScope: {
+        store: "agent-schedule",
+        directory: agendaStore.dir,
+      },
+      sourceId: snapshot.id,
+    });
+    if (ambiguousLegacy) {
+      throw agendaError(
+        "AGENDA_SCHEDULER_MIGRATION_SOURCE_UNBOUND",
+        `Legacy Agenda migration uses a non-canonical path scope and cannot be bound safely: ${snapshot.id}`,
+      );
+    }
+  }
+  const desired = buildAgendaSchedulerJob(snapshot);
+  desired.authority = bindSchedulerAuthorityPolicy(
+    schedulerStore,
+    desired.authority,
+  );
+  const sourceDigest = agendaMigrationSourceDigest(entry);
+  const sourceSnapshot = agendaMigrationSourceSnapshot(entry);
+  if (prepared) {
+    const migrationEntries = prepared.entries.filter(
+      (candidate) =>
+        candidate.domain === "agenda" && candidate.sourceId === snapshot.id,
+    );
+    if (prepared.entries.length !== 1 || migrationEntries.length !== 1) {
+      throw agendaError(
+        "AGENDA_SCHEDULER_MIGRATION_DOMAIN_MISMATCH",
+        "Agenda entry belongs to an invalid mixed-domain migration",
+      );
+    }
+    const [migrationEntry] = migrationEntries;
+    schedulerStore.bindDomainMigrationSourceLocator({
+      migrationId: prepared.id,
+      entryId: migrationEntry.entryId,
+      sourceLocator,
+      expectedSourceDigest: migrationEntry.sourceDigest,
+      expectedTargetJobId: migrationEntry.targetJobId,
+    });
+    prepared = schedulerStore.getDomainMigration(prepared.id);
+  } else {
+    prepared = schedulerStore.prepareDomainMigration({
+      entries: [
+        {
+          domain: "agenda",
+          sourceId: snapshot.id,
+          sourceScope,
+          sourceLocator,
+          source: sourceSnapshot,
+          targetJob: desired,
+          rollbackStrategy: "disable",
+        },
+      ],
+    });
+  }
+  if (
+    prepared.entries.length !== 1 ||
+    prepared.entries[0].domain !== "agenda"
+  ) {
+    throw agendaError(
+      "AGENDA_SCHEDULER_MIGRATION_DOMAIN_MISMATCH",
+      "Agenda entry belongs to an invalid mixed-domain migration",
+    );
+  }
+  const expectedJournalDigest = schedulerMigrationSourceDigest(sourceSnapshot);
+  if (
+    prepared.entries[0].sourceDigest !== expectedJournalDigest ||
+    prepared.entries[0].targetJobId !== desired.id
+  ) {
+    throw agendaError(
+      "AGENDA_SCHEDULER_MIGRATION_SOURCE_CHANGED",
+      `Agenda entry changed after its scheduler migration started: ${snapshot.id}`,
+    );
+  }
+  let migration = prepared;
+  if (migration.state === "rolled_back" || migration.state === "rolling_back") {
+    throw agendaError(
+      "AGENDA_SCHEDULER_MIGRATION_STATE_CONFLICT",
+      `Agenda migration cannot resume from state ${migration.state}`,
+    );
+  }
+  if (migration.state === "retired") {
+    const migrationEntry = migration.entries[0];
+    agendaStore.retireForSchedulerMigration(snapshot.id, {
+      migrationId: migration.id,
+      sourceDigest,
+      targetJobId: desired.id,
+      retirementToken: migrationEntry.retirementToken,
+    });
+    return migration;
+  }
+  if (migration.state === "prepared") {
+    agendaStore.prepareSchedulerMigration(snapshot.id, {
+      migrationId: migration.id,
+      sourceDigest,
+      targetJobId: desired.id,
+    });
+    migration = schedulerStore.applyDomainMigration(migration.id);
+  }
+  if (migration.state === "applied") {
+    migration = schedulerStore.verifyDomainMigration(migration.id, {
+      sources: [
+        {
+          entryId: migration.entries[0].entryId,
+          source: agendaMigrationSourceSnapshot(entry),
+        },
+      ],
+    });
+  }
+  const retiring =
+    migration.state === "retiring"
+      ? migration
+      : schedulerStore.beginDomainMigrationRetirement(migration.id);
+  const retiringEntry = retiring.entries[0];
+  const retired = agendaStore.retireForSchedulerMigration(snapshot.id, {
+    migrationId: prepared.id,
+    sourceDigest,
+    targetJobId: desired.id,
+    retirementToken: retiringEntry.retirementToken,
+  });
+  schedulerStore.confirmDomainMigrationEntryRetired({
+    migrationId: prepared.id,
+    entryId: retiringEntry.entryId,
+    retirementToken: retiringEntry.retirementToken,
+    source: retired,
+  });
+  return schedulerStore.getDomainMigration(prepared.id);
+}
+
+export function rollbackAgendaSchedulerMigration({
+  agendaStore,
+  schedulerStore,
+  migrationId,
+}) {
+  const directory = canonicalSchedulerSourcePath(agendaStore.dir);
+  const assertRollbackBinding = (migration) => {
+    if (
+      migration?.id !== migrationId ||
+      !Array.isArray(migration.entries) ||
+      migration.entries.length === 0 ||
+      migration.entries.some((entry) => entry.domain !== "agenda")
+    ) {
+      throw agendaError(
+        "AGENDA_SCHEDULER_MIGRATION_DOMAIN_MISMATCH",
+        "Agenda rollback cannot operate on a mixed-domain migration",
+      );
+    }
+    for (const entry of migration.entries) {
+      const locator = entry.sourceLocator;
+      if (
+        locator?.schemaVersion !== 1 ||
+        locator.type !== "agenda-store" ||
+        locator.directory !== directory
+      ) {
+        throw agendaError(
+          "AGENDA_SCHEDULER_MIGRATION_SOURCE_UNBOUND",
+          `Agenda rollback source locator does not match its store: ${entry.sourceId}`,
+        );
+      }
+    }
+    return migration;
+  };
+  const current = assertRollbackBinding(
+    schedulerStore.getDomainMigration(migrationId),
+  );
+  if (current.state === "rolled_back") {
+    return { ...current, deduplicated: true };
+  }
+  const migration = assertRollbackBinding(
+    schedulerStore.beginDomainMigrationRollback(migrationId),
+  );
+  if (migration.state === "rolled_back") return migration;
+  const entries = migration.entries;
+  for (const entry of entries) {
+    if (entry.state === "rolled_back") continue;
+    schedulerStore.restoreDomainMigrationEntrySource({
+      migrationId,
+      entryId: entry.entryId,
+      retirementToken: entry.retirementToken,
+      restoreSource: () => {
+        const current = agendaStore.get(entry.sourceId);
+        const restored = current.schedulerMigration
+          ? agendaStore.restoreFromSchedulerMigration(entry.sourceId, {
+              migrationId,
+              sourceDigest: agendaMigrationSourceDigest(current),
+              targetJobId: entry.targetJobId,
+              retirementToken: entry.retirementToken,
+            })
+          : current;
+        return agendaMigrationSourceSnapshot(restored);
+      },
+    });
+  }
+  return schedulerStore.getDomainMigration(migrationId);
+}
+
 export function enqueueAgendaEntry(schedulerStore, entry) {
   const snapshot = agendaEntrySnapshot(entry);
   const job = syncAgendaSchedulerJob(schedulerStore, snapshot);
@@ -216,7 +609,7 @@ export function authorizeAgendaOccurrence({ job, occurrence }) {
       authority?.principal?.id === entry.id &&
       Array.isArray(authority?.requestedCapabilities) &&
       authority.requestedCapabilities.length === 1 &&
-      authority.requestedCapabilities[0] === AGENDA_SCHEDULER_CAPABILITY &&
+      authority.requestedCapabilities[0] === capabilityForEntry(entry) &&
       payload.snapshotDigest === expectedDigest;
     return {
       allowed,
@@ -231,7 +624,11 @@ function recoveredResult(entry, evidence) {
   const result =
     evidence.result && typeof evidence.result === "object"
       ? evidence.result
-      : { id: entry.id, kind: entry.kind, action: "fired" };
+      : {
+          id: entry.id,
+          kind: entry.kind,
+          action: entry.kind === "monitor" ? "checked" : "fired",
+        };
   return { ...result, recovered: true };
 }
 
@@ -251,6 +648,8 @@ function matchingExecutionEvidence(
 export function createAgendaSchedulerAdapter({
   agendaStore,
   runAgent,
+  runMonitor,
+  notifyMonitor,
   now = Date.now,
 } = {}) {
   if (
@@ -278,6 +677,40 @@ export function createAgendaSchedulerAdapter({
   }
   return {
     kind: AGENDA_SCHEDULER_KIND,
+    async adjudicate({ occurrence, adjudication }) {
+      const payload = occurrence.payload;
+      const expected = agendaEntrySnapshot(payload?.entry);
+      const expectedDigest = agendaEntrySnapshotDigest(expected);
+      if (
+        payload.snapshotDigest !== expectedDigest ||
+        typeof agendaStore.adjudicateSchedulerExecution !== "function"
+      ) {
+        throw agendaError(
+          "AGENDA_SCHEDULER_ADJUDICATION_UNSUPPORTED",
+          `Agenda adjudication cannot be applied: ${occurrence.id}`,
+        );
+      }
+      agendaStore.adjudicateSchedulerExecution(expected.id, {
+        occurrenceId: occurrence.id,
+        snapshotDigest: expectedDigest,
+        attempt: adjudication.expectedAttempt,
+        decision: adjudication.decision,
+        requestId: adjudication.requestId,
+        atMs: now(),
+      });
+      if (adjudication.decision === "confirmed_applied") {
+        return {
+          settled: true,
+          result: {
+            id: expected.id,
+            kind: expected.kind,
+            action: "adjudicated-applied",
+            adjudicationRequestId: adjudication.requestId,
+          },
+        };
+      }
+      return { continue: true };
+    },
     async execute({ occurrence }) {
       const payload = occurrence.payload;
       const expected = agendaEntrySnapshot(payload?.entry);
@@ -309,7 +742,7 @@ export function createAgendaSchedulerAdapter({
         if (prior.status === "running") {
           throw agendaError(
             "AGENDA_SCHEDULER_OUTCOME_UNKNOWN",
-            `Agenda agent outcome is unknown; refusing duplicate execution: ${expected.id}`,
+            `Agenda execution outcome is unknown; refusing duplicate execution: ${expected.id}`,
           );
         }
       } else if (prior?.status === "running") {
@@ -347,14 +780,54 @@ export function createAgendaSchedulerAdapter({
         throw stale;
       }
 
+      let observation = null;
+      let action = null;
       try {
-        await runAgent({
-          entry: expected,
-          prompt: expected.prompt,
-          runPolicy: expected.runPolicy,
-          occurrenceId: occurrence.id,
-          attempt: occurrence.attempt,
-        });
+        if (expected.kind === "monitor") {
+          if (typeof runMonitor !== "function") {
+            throw agendaError(
+              "AGENDA_SCHEDULER_MONITOR_RUNNER_REQUIRED",
+              "Agenda scheduler monitor execution requires a monitor runner",
+            );
+          }
+          observation = normalizeMonitorObservation(
+            expected,
+            await runMonitor({
+              entry: expected,
+              occurrenceId: occurrence.id,
+              attempt: occurrence.attempt,
+            }),
+          );
+          action = {
+            id: expected.id,
+            kind: expected.kind,
+            action: observation.matched
+              ? observation.duplicate
+                ? "duplicate"
+                : "matched"
+              : "checked",
+            ...(observation.matched
+              ? {
+                  event_id: observation.eventId,
+                  authority: observation.authority,
+                }
+              : {}),
+            ...(observation.truncated ? { truncated: true } : {}),
+          };
+        } else {
+          await runAgent({
+            entry: expected,
+            prompt: expected.prompt,
+            runPolicy: expected.runPolicy,
+            occurrenceId: occurrence.id,
+            attempt: occurrence.attempt,
+          });
+          action = {
+            id: expected.id,
+            kind: expected.kind,
+            action: "fired",
+          };
+        }
       } catch (error) {
         let failurePersisted = false;
         try {
@@ -389,14 +862,16 @@ export function createAgendaSchedulerAdapter({
         throw agendaError(
           typeof error?.code === "string"
             ? error.code
-            : "AGENDA_AGENT_EXECUTION_FAILED",
+            : expected.kind === "monitor"
+              ? "AGENDA_MONITOR_EXECUTION_FAILED"
+              : "AGENDA_AGENT_EXECUTION_FAILED",
           typeof error?.message === "string"
             ? error.message
-            : `Agenda agent execution failed: ${expected.id}`,
+            : `Agenda ${expected.kind === "monitor" ? "monitor" : "agent"} execution failed: ${expected.id}`,
           undefined,
           error,
           {
-            retryable: true,
+            retryable: error?.retryable !== false,
             retryAt: normalizeEpochMs(
               Number(now()) + AGENDA_SCHEDULER_RETRY_DELAY_MS,
               "agenda.retryAt",
@@ -405,21 +880,50 @@ export function createAgendaSchedulerAdapter({
         );
       }
 
-      const action = {
-        id: expected.id,
-        kind: expected.kind,
-        action: "fired",
-      };
       try {
-        agendaStore.completeSchedulerExecution(expected.id, {
+        const completed = agendaStore.completeSchedulerExecution(expected.id, {
           occurrenceId: occurrence.id,
           snapshotDigest: expectedDigest,
           attempt: occurrence.attempt,
           outcome: "succeeded",
           result: action,
+          ...(observation
+            ? {
+                monitorCheck: {
+                  matched: observation.matched,
+                  mtimeMs: observation.mtimeMs,
+                  eventId: observation.eventId,
+                  authority: observation.authority,
+                },
+              }
+            : {}),
           atMs: now(),
         });
-        return action;
+        const persistedAction = completed.schedulerExecution?.result || action;
+        if (
+          observation?.matched &&
+          !observation.duplicate &&
+          observation.notification
+        ) {
+          if (typeof notifyMonitor !== "function") {
+            return {
+              ...persistedAction,
+              notifyError: "Agenda monitor notification handler is unavailable",
+            };
+          }
+          try {
+            await notifyMonitor(observation.notification);
+          } catch (notifyError) {
+            return {
+              ...persistedAction,
+              notifyError:
+                typeof notifyError?.message === "string"
+                  ? notifyError.message
+                  : String(notifyError),
+            };
+          }
+        }
+        return persistedAction;
       } catch (completionError) {
         const persisted = agendaStore.get(expected.id);
         if (
@@ -454,10 +958,14 @@ export class AgendaSchedulerBridge {
     agendaStore,
     schedulerStore,
     runAgent,
+    runMonitor,
+    notifyMonitor,
     now = Date.now,
     ownerId,
     leaseMs,
     renewIntervalMs,
+    authorityResolver,
+    migrateLegacy = true,
   } = {}) {
     if (typeof now !== "function") {
       throw agendaError(
@@ -468,10 +976,29 @@ export class AgendaSchedulerBridge {
     this.agendaStore = agendaStore;
     this.schedulerStore = schedulerStore;
     this.now = now;
+    this.migrateLegacy = migrateLegacy !== false;
     this.runtime = new SchedulerRuntime({
       store: schedulerStore,
-      adapters: [createAgendaSchedulerAdapter({ agendaStore, runAgent, now })],
-      authorize: authorizeAgendaOccurrence,
+      adapters: [
+        createAgendaSchedulerAdapter({
+          agendaStore,
+          runAgent,
+          runMonitor,
+          notifyMonitor,
+          now,
+        }),
+      ],
+      authorize:
+        authorityResolver ||
+        createSchedulerAuthorityResolver({
+          store: schedulerStore,
+          validate: authorizeAgendaOccurrence,
+          units: ({ occurrence }) =>
+            Math.max(
+              1,
+              Number(occurrence?.payload?.entry?.runPolicy?.maxTurns) || 1,
+            ),
+        }),
       ...(ownerId === undefined ? {} : { ownerId }),
       ...(leaseMs === undefined ? {} : { leaseMs }),
       ...(renewIntervalMs === undefined ? {} : { renewIntervalMs }),
@@ -481,6 +1008,31 @@ export class AgendaSchedulerBridge {
   async runDue({ signal } = {}) {
     const results = [];
     const observedOccurrences = new Set();
+    if (!signal?.aborted && this.migrateLegacy) {
+      const sourceScope = {
+        store: "agent-schedule",
+        directory: canonicalSchedulerSourcePath(this.agendaStore.dir),
+      };
+      const candidates = this.agendaStore.list().filter((entry) => {
+        const activeMigration =
+          this.schedulerStore.getActiveDomainMigrationBySource({
+            domain: "agenda",
+            sourceScope,
+            sourceId: entry.id,
+          });
+        if (entry.schedulerMigration) {
+          return activeMigration?.state !== "retired";
+        }
+        return activeMigration?.state !== undefined;
+      });
+      for (const entry of candidates) {
+        migrateAgendaSchedulerEntry({
+          agendaStore: this.agendaStore,
+          schedulerStore: this.schedulerStore,
+          entry,
+        });
+      }
+    }
     const recovered = await this.runtime.runUntilIdle({
       limit: 10_000,
       signal,
@@ -503,8 +1055,9 @@ export class AgendaSchedulerBridge {
 
     const now = normalizeEpochMs(Number(this.now()), "now");
     const due = [
-      ...this.agendaStore.due("wakeup", now),
-      ...this.agendaStore.due("cron", now),
+      ...this.agendaStore.due("wakeup", now, { schedulerMigration: true }),
+      ...this.agendaStore.due("cron", now, { schedulerMigration: true }),
+      ...this.agendaStore.due("monitor", now, { schedulerMigration: true }),
     ];
     for (const entry of due) {
       const occurrence = enqueueAgendaEntry(this.schedulerStore, entry);
@@ -520,6 +1073,28 @@ export class AgendaSchedulerBridge {
         result,
       });
     }
+    if (this.migrateLegacy) {
+      const candidates = this.agendaStore
+        .list()
+        .filter(
+          (entry) =>
+            !entry.schedulerMigration &&
+            [undefined, "succeeded"].includes(
+              entry.schedulerExecution?.status,
+            ) &&
+            !entry.executionLease &&
+            ((entry.kind === "wakeup" && entry.status === "pending") ||
+              (["cron", "monitor"].includes(entry.kind) &&
+                entry.status === "active")),
+        );
+      for (const entry of candidates) {
+        migrateAgendaSchedulerEntry({
+          agendaStore: this.agendaStore,
+          schedulerStore: this.schedulerStore,
+          entry,
+        });
+      }
+    }
     return results;
   }
 }