@inetafrica/open-claudia 2.14.8 → 3.0.0

package/core/scheduler.js

@@ -1,258 +1,563 @@
-// Unified scheduler — owns every timer the bot has running. Replaces
-// the old core/cron.js. Loads jobs.json on boot, schedules wakeups
-// (setTimeout) and crons (node-cron), and fires each one in the right
-// chat context with the right session pinned.
-//
-// When a wakeup fires the agent wakes up inside the SAME Claude session
-// it was in when it scheduled the wakeup (per design choice a/i). If
-// the channel is busy with a live turn the fire is deferred 30s and
-// retried. One-shot wakeups self-delete; crons persist.
+// Provider-aware durable scheduler. Every occurrence executes the immutable
+// user/project/provider/settings/session tuple captured when it was created.
+// One-shots are removed only after a terminal successful RunResult and a
+// durable success marker; failures retain the same occurrence ID for bounded
+// retry and eventually become explicit dead letters.
 
-const path = require("path");
+"use strict";
+
+const crypto = require("crypto");
 const fs = require("fs");
+const path = require("path");
 const cron = require("node-cron");
 
-const { CRONS_FILE, WORKSPACE, CHAT_ID } = require("./config");
-const jobs = require("./jobs");
-const { runInChat } = require("./context");
-const { getUserState, userStates } = require("./state");
-const { canonicalForTelegram, canonicalForChannel } = require("./identity");
-const { send } = require("./io");
+const {
+  CRONS_FILE,
+  WORKSPACE,
+  config,
+} = require("./config");
+const defaultJobsStore = require("./jobs");
+const { runInChat: defaultRunInChat } = require("./context");
+const {
+  currentState,
+  getActiveProvider,
+  getProjectKey,
+  getProviderSession,
+  getProviderSettings,
+  getUserState,
+} = require("./state");
+const { canonicalForChannel } = require("./identity");
+const { send: defaultSend } = require("./io");
+const { providerStatus: defaultProviderStatus } = require("./providers");
+const { redactSensitive } = require("./redact");
 
 const MISSED_WAKEUP_GRACE_MS = 60 * 60 * 1000;
-const DEFER_BUSY_MS = 30 * 1000;
+const RETRY_DELAY_MS = 30 * 1000;
+const BUSY_DELAY_MS = 30 * 1000;
 
-const timers = new Map();
-let adapters = [];
-
-function setAdapters(list) {
-  adapters = Array.isArray(list) ? list.slice() : [];
+function uniqueId(prefix = "occ") {
+  return typeof crypto.randomUUID === "function"
+    ? `${prefix}-${crypto.randomUUID()}`
+    : `${prefix}-${Date.now()}-${crypto.randomBytes(6).toString("hex")}`;
 }
 
-function resolveAdapter(job) {
-  if (job.adapter) {
-    const byId = adapters.find((a) => a.id === job.adapter);
-    if (byId) return byId;
-  }
-  if (job.adapterType) {
-    const byType = adapters.find((a) => a.type === job.adapterType);
-    if (byType) return byType;
-  }
-  return adapters[0] || null;
+function parseFallbacks(value) {
+  if (Array.isArray(value)) return [...new Set(value.map((item) => String(item).trim().toLowerCase()).filter(Boolean))];
+  return [...new Set(String(value || "").split(",").map((item) => item.trim().toLowerCase()).filter(Boolean))];
 }
 
-function projectDir(job) {
-  if (!job.project) return null;
-  if (path.isAbsolute(job.project)) return job.project;
-  if (!WORKSPACE) return null;
-  return path.join(WORKSPACE, job.project);
+function terminalRunSucceeded(result) {
+  if (!result || result.ok !== true || (result.status && result.status !== "succeeded")) return false;
+  if (result.persistence && Object.values(result.persistence).some((stage) => stage && stage.ok === false)) return false;
+  if (!result.delivery || result.delivery.ok !== true) return false;
+  return true;
 }
 
-function deriveCanonicalUserId(adapter, job) {
-  if (job.canonicalUserId) return job.canonicalUserId;
-  if (!adapter) return null;
-  return canonicalForChannel(adapter.type, job.channelId);
+function providerIsRunnable(status) {
+  if (!status || status.availability?.state !== "available") return false;
+  if (status.compatibility?.state === "incompatible") return false;
+  if (status.auth?.state === "unauthenticated") return false;
+  return true;
 }
 
-function deriveUserId(adapter, job) {
-  if (job.userId) return String(job.userId);
-  if (adapter && adapter.type === "telegram") return String(job.channelId);
-  return String(job.canonicalUserId || job.channelId || "");
+function stableFailure(errorOrResult) {
+  const error = errorOrResult?.error || errorOrResult;
+  const code = String(error?.code || errorOrResult?.status || "SCHEDULED_RUN_FAILED").slice(0, 80);
+  const message = redactSensitive(String(
+    error?.message
+      || errorOrResult?.diagnostic
+      || (Number.isFinite(errorOrResult?.exitCode) ? `Provider exited with code ${errorOrResult.exitCode}` : "Scheduled provider run failed"),
+  )).slice(0, 500);
+  return { code, message };
 }
 
-async function fireJob(job, retry = 0) {
-  const adapter = resolveAdapter(job);
-  if (!adapter) {
-    console.error(`scheduler: no adapter for job ${job.id} (${job.label || job.kind})`);
-    return;
+function createSchedulerService(dependencies = {}) {
+  const jobsStore = dependencies.jobsStore || defaultJobsStore;
+  const workspace = dependencies.workspace === undefined ? WORKSPACE : dependencies.workspace;
+  const now = dependencies.now || Date.now;
+  const setTimer = dependencies.setTimer || setTimeout;
+  const clearTimer = dependencies.clearTimer || clearTimeout;
+  const scheduleCron = dependencies.scheduleCron || ((expression, callback) => cron.schedule(expression, callback, { noOverlap: true }));
+  const validateCron = dependencies.validateCron || cron.validate;
+  const runInChat = dependencies.runInChat || defaultRunInChat;
+  const stateForUser = dependencies.getUserState || getUserState;
+  const send = dependencies.send || defaultSend;
+  const providerStatus = dependencies.providerStatus || defaultProviderStatus;
+  const fallbackProviders = parseFallbacks(
+    dependencies.fallbackProviders === undefined ? config.PROVIDER_FALLBACKS : dependencies.fallbackProviders,
+  );
+  const retryDelayMs = Number.isFinite(dependencies.retryDelayMs) ? dependencies.retryDelayMs : RETRY_DELAY_MS;
+  const busyDelayMs = Number.isFinite(dependencies.busyDelayMs) ? dependencies.busyDelayMs : BUSY_DELAY_MS;
+  const missedGraceMs = Number.isFinite(dependencies.missedGraceMs) ? dependencies.missedGraceMs : MISSED_WAKEUP_GRACE_MS;
+  const occurrenceIdFactory = dependencies.occurrenceIdFactory || (() => uniqueId("occ"));
+  const legacyCronsFile = dependencies.legacyCronsFile === undefined
+    ? (dependencies.jobsStore ? null : CRONS_FILE)
+    : dependencies.legacyCronsFile;
+  const runInProvider = dependencies.runAgent || ((...args) => require("./runner").runAgent(...args));
+  const admit = dependencies.admitRunContext || ((...args) => require("./runner").admitRunContext(...args));
+  const timers = new Map();
+  let adapters = Array.isArray(dependencies.adapters) ? dependencies.adapters.slice() : [];
+
+  function setAdapters(list) {
+    adapters = Array.isArray(list) ? list.slice() : [];
   }
-  const canonicalUserId = deriveCanonicalUserId(adapter, job);
-  const userId = deriveUserId(adapter, job);
-
-  const ctx = {
-    adapter,
-    channelId: String(job.channelId),
-    canonicalUserId,
-    userId,
-    transport: adapter.type,
-    raw: null,
-  };
 
-  let deferred = false;
-  await runInChat(ctx, async () => {
-    const state = getUserState(canonicalUserId);
-    if (state.runningProcess) {
-      if (retry < 4) {
-        console.log(`scheduler: ${job.id} busy, deferring ${DEFER_BUSY_MS / 1000}s (retry ${retry + 1})`);
-        deferred = true;
-        setTimeout(() => fireJob(job, retry + 1), DEFER_BUSY_MS);
-        return;
-      }
-      console.warn(`scheduler: ${job.id} still busy after retries, skipping`);
-      jobs.update(job.id, { lastFireAt: Date.now(), lastFireOk: false });
-      return;
+  function resolveAdapter(job) {
+    if (job.adapter) {
+      const exact = adapters.find((adapter) => adapter.id === job.adapter);
+      if (exact) return exact;
+    }
+    if (job.adapterType) {
+      const byType = adapters.find((adapter) => adapter.type === job.adapterType);
+      if (byType) return byType;
     }
+    return null;
+  }
+
+  function projectDescriptor(job) {
+    const explicitDir = job.projectDir && path.isAbsolute(job.projectDir) ? job.projectDir : null;
+    const legacyAbsolute = job.project && path.isAbsolute(job.project) ? job.project : null;
+    const name = legacyAbsolute ? path.basename(legacyAbsolute) : String(job.project || "");
+    const dir = explicitDir || legacyAbsolute || (workspace && name ? path.join(workspace, name) : null);
+    return { name, dir: dir || workspace || process.cwd() };
+  }
 
-    const cwd = projectDir(job) || (state.currentSession && state.currentSession.dir) || WORKSPACE || process.cwd();
-    const label = job.label || (job.kind === "cron" ? "Scheduled cron" : "Scheduled wakeup");
-
-    try {
-      await send(`Wakeup: ${label}`);
-    } catch (e) { /* non-fatal */ }
-
-    const wrappedPrompt = job.kind === "cron"
-      ? `[Scheduled cron \"${label}\" fired at ${new Date().toISOString()}]\n${job.prompt}`
-      : `[Scheduled wakeup \"${label}\" fired at ${new Date().toISOString()}]\n${job.prompt}`;
-
-    const { runClaude } = require("./runner");
-    const runOpts = {};
-    // Join the channel's live conversation. Only fall back to the wakeup's
-    // frozen sessionId when there's no live pointer (cold start) — otherwise
-    // a stale, compacted-away id would yank the channel onto a dead thread.
-    if (!state.lastSessionId && job.sessionId) runOpts.resumeSessionId = job.sessionId;
-    try {
-      await runClaude(wrappedPrompt, cwd, null, runOpts);
-      jobs.update(job.id, { lastFireAt: Date.now(), lastFireOk: true });
-    } catch (e) {
-      console.error(`scheduler: ${job.id} run error:`, e.message);
-      jobs.update(job.id, { lastFireAt: Date.now(), lastFireOk: false });
-      try { await send(`Wakeup "${label}" failed: ${e.message}`); } catch (_) {}
+  function resolveCompactionLineage(state, job) {
+    let sessionId = job.sessionId || null;
+    if (!sessionId) return { sessionId: null, attachSession: true };
+    const seen = new Set();
+    while (sessionId && !seen.has(sessionId)) {
+      seen.add(sessionId);
+      const successor = Object.values(state?.completedCompactions || {}).find((entry) => (
+        entry?.provider === job.provider
+        && entry?.project === job.project
+        && entry?.previousSessionId === sessionId
+        && entry?.newSessionId
+      ));
+      if (!successor) break;
+      sessionId = successor.newSessionId;
     }
-  });
-
-  // Only delete a one-shot wakeup once it actually ran (or was skipped).
-  // Removing it while a busy-deferral is pending would leave the retry
-  // living only in an in-memory setTimeout — a restart during that
-  // window (e.g. /upgrade) would silently lose the wakeup.
-  if (job.kind === "wakeup" && !deferred) {
-    jobs.remove(job.id);
-    timers.delete(job.id);
+    const live = getProviderSession(state, job.provider, job.project);
+    return {
+      sessionId,
+      // A historical scheduled branch may run, but it must not replace an
+      // unrelated live branch. A proven compaction successor can advance it.
+      attachSession: !live || live === sessionId,
+    };
   }
-}
 
-function scheduleJob(job) {
-  if (timers.has(job.id)) {
-    const prev = timers.get(job.id);
-    if (prev.stop) prev.stop();
-    if (prev.timeout) clearTimeout(prev.timeout);
-    timers.delete(job.id);
+  function providerStatusSafe(provider) {
+    try { return providerStatus(provider); }
+    catch (error) {
+      return {
+        availability: { state: "missing", reason: error.message },
+        compatibility: { state: "not_checked" },
+        auth: { state: "not_checked" },
+      };
+    }
   }
-  if (job.kind === "wakeup") {
-    const delay = Math.max(0, (job.fireAt || 0) - Date.now());
-    const timeout = setTimeout(() => fireJob(job), delay);
+
+  function executionTarget(job, state) {
+    if (providerIsRunnable(providerStatusSafe(job.provider))) {
+      const lineage = resolveCompactionLineage(state, job);
+      return {
+        provider: job.provider,
+        providerSettings: job.providerSettings || {},
+        sessionId: lineage.sessionId,
+        attachSession: lineage.attachSession,
+        fallbackFrom: null,
+        fresh: !lineage.sessionId,
+      };
+    }
+    for (const fallback of fallbackProviders) {
+      if (fallback === job.provider || !["claude", "codex"].includes(fallback)) continue;
+      if (!providerIsRunnable(providerStatusSafe(fallback))) continue;
+      return {
+        provider: fallback,
+        providerSettings: {},
+        sessionId: null,
+        attachSession: false,
+        fallbackFrom: job.provider,
+        fresh: true,
+      };
+    }
+    return null;
+  }
+
+  function wrappedPrompt(job, target) {
+    const firedAt = new Date(now()).toISOString();
+    const header = job.kind === "cron" ? "Scheduled cron" : "Scheduled wakeup";
+    if (target.fallbackFrom) {
+      return [
+        `[${header} "${job.label}" fired at ${firedAt}; occurrence ${job.occurrenceId}]`,
+        `[Archived provider-neutral brief: the originating ${target.fallbackFrom} provider is unavailable. Its native session is not being resumed; this explicitly configured fallback starts fresh.]`,
+        job.prompt,
+      ].join("\n");
+    }
+    return `[${header} "${job.label}" fired at ${firedAt}; occurrence ${job.occurrenceId}]\n${job.prompt}`;
+  }
+
+  function unscheduleJob(id) {
+    const timer = timers.get(id);
+    if (!timer) return;
+    try { timer.stop?.(); } catch (_) {}
+    try { if (timer.timeout) clearTimer(timer.timeout); } catch (_) {}
+    timers.delete(id);
+  }
+
+  function armRetry(job, delay = null) {
+    unscheduleJob(job.id);
+    if (job.disabled || job.status === "dead-letter" || job.status === "succeeded") return;
+    const wait = delay === null
+      ? Math.max(0, Number(job.nextAttemptAt || now()) - now())
+      : Math.max(0, delay);
+    const timeout = setTimer(() => fireJob(job.id, { reason: "retry" }), wait);
     timers.set(job.id, { timeout });
-  } else if (job.kind === "cron") {
-    if (!cron.validate(job.schedule)) {
-      console.error(`scheduler: invalid cron schedule for ${job.id}: ${job.schedule}`);
-      return;
+  }
+
+  function markFailure(job, failure, options = {}) {
+    const latest = jobsStore.get(job.id) || job;
+    const attemptCount = options.attemptAlreadyCounted
+      ? Math.max(1, latest.attemptCount || 0)
+      : (latest.attemptCount || 0) + 1;
+    const dead = attemptCount >= (latest.maxAttempts || 1);
+    const patch = {
+      status: dead ? "dead-letter" : "failed",
+      disabled: dead,
+      attemptCount,
+      nextAttemptAt: dead ? null : now() + retryDelayMs,
+      lastFireAt: now(),
+      lastFireOk: false,
+      lastError: stableFailure(failure),
+    };
+    const updated = jobsStore.update(job.id, patch) || { ...latest, ...patch };
+    if (!dead) armRetry(updated);
+    else unscheduleJob(job.id);
+    return { ok: false, status: updated.status, job: updated, error: updated.lastError };
+  }
+
+  function markBusy(job) {
+    const latest = jobsStore.get(job.id) || job;
+    const busyDeferralCount = (latest.busyDeferralCount || 0) + 1;
+    const dead = busyDeferralCount >= (latest.maxAttempts || 1);
+    const patch = {
+      status: dead ? "dead-letter" : "deferred",
+      disabled: dead,
+      busyDeferralCount,
+      nextAttemptAt: dead ? null : now() + busyDelayMs,
+      lastError: dead ? { code: "SCHEDULED_BUSY_EXHAUSTED", message: "Channel remained busy through every bounded deferral" } : null,
+    };
+    const updated = jobsStore.update(job.id, patch) || { ...latest, ...patch };
+    if (!dead) armRetry(updated, busyDelayMs);
+    else unscheduleJob(job.id);
+    return { ok: false, deferred: !dead, status: updated.status, job: updated };
+  }
+
+  async function settleSuccess(job, result, target) {
+    const successPatch = {
+      status: "succeeded",
+      disabled: false,
+      nextAttemptAt: null,
+      lastFireAt: now(),
+      lastFireOk: true,
+      lastError: null,
+      completedOccurrenceId: job.occurrenceId,
+      lastProvider: target.provider,
+      fallbackFromProvider: target.fallbackFrom,
+    };
+    let marked;
+    try { marked = jobsStore.update(job.id, successPatch); }
+    catch (error) { return { ok: false, status: "failed", error: stableFailure(error), result }; }
+    if (!marked) return { ok: false, status: "failed", error: { code: "JOB_PERSIST_FAILED", message: "Scheduled success marker was not persisted" }, result };
+
+    if (job.kind === "wakeup") {
+      try {
+        const removed = jobsStore.remove(job.id);
+        if (!removed) throw new Error("successful one-shot could not be removed after its durable success marker");
+        unscheduleJob(job.id);
+      } catch (error) {
+        // The succeeded marker prevents a restart from executing this
+        // occurrence twice; init() will retry only the final removal.
+        return { ok: false, status: "cleanup-pending", error: stableFailure(error), result };
+      }
+      return { ok: true, status: "succeeded", result };
     }
-    const task = cron.schedule(job.schedule, () => fireJob(job));
-    timers.set(job.id, { stop: () => task.stop() });
+
+    const nextOccurrence = occurrenceIdFactory(job);
+    const reset = jobsStore.update(job.id, {
+      status: "pending",
+      disabled: false,
+      occurrenceId: nextOccurrence,
+      attemptCount: 0,
+      busyDeferralCount: 0,
+      nextAttemptAt: null,
+    });
+    if (reset && timers.get(job.id)?.timeout) scheduleJob(reset);
+    return reset
+      ? { ok: true, status: "succeeded", result, job: reset }
+      : { ok: false, status: "failed", error: { code: "JOB_PERSIST_FAILED", message: "Recurring job occurrence was not advanced" }, result };
   }
-}
 
-function unscheduleJob(id) {
-  const t = timers.get(id);
-  if (!t) return;
-  if (t.stop) t.stop();
-  if (t.timeout) clearTimeout(t.timeout);
-  timers.delete(id);
-}
+  async function fireJob(idOrJob, options = {}) {
+    const requested = typeof idOrJob === "string" ? jobsStore.get(idOrJob) : idOrJob;
+    const job = requested?.id && jobsStore.get(requested.id) ? jobsStore.get(requested.id) : requested;
+    if (!job) return { ok: false, status: "missing" };
+    if (job.disabled || job.status === "dead-letter" || job.status === "archived") {
+      return { ok: false, status: job.status, skipped: true };
+    }
+    if (job.status === "running" && Number(job.nextAttemptAt || 0) > now()) {
+      return { ok: false, status: "running", skipped: true, inFlight: true };
+    }
+    if (job.status === "succeeded" && job.kind === "wakeup") {
+      try { jobsStore.remove(job.id); } catch (_) {}
+      unscheduleJob(job.id);
+      return { ok: true, status: "succeeded", finalized: true };
+    }
 
-function migrateLegacyCrons() {
-  try {
-    if (!CRONS_FILE || !fs.existsSync(CRONS_FILE)) return 0;
-    const raw = JSON.parse(fs.readFileSync(CRONS_FILE, "utf-8"));
-    if (!Array.isArray(raw) || raw.length === 0) return 0;
-    const existing = new Set(jobs.listAll().map((j) => j.id));
-    const tg = adapters.find((a) => a.type === "telegram");
-    const adapterId = tg ? tg.id : (adapters[0] && adapters[0].id);
-    const adapterType = tg ? "telegram" : (adapters[0] && adapters[0].type);
-    const channelId = tg ? (CHAT_ID || "") : "";
-    const canonicalUserId = adapterType === "telegram"
-      ? canonicalForTelegram(CHAT_ID || "")
-      : canonicalForChannel(adapterType || "", channelId);
-    let migrated = 0;
-    for (const c of raw) {
-      if (!c || !c.schedule || !c.prompt) continue;
-      if (c.id && existing.has(c.id)) continue;
-      jobs.add({
-        id: c.id || jobs.nextId("cron"),
-        kind: "cron",
-        adapter: adapterId,
-        adapterType,
-        channelId: String(channelId),
-        canonicalUserId,
-        project: c.project || null,
-        prompt: c.prompt,
-        label: c.label || (c.prompt || "").slice(0, 50),
-        source: "user",
-        schedule: c.schedule,
-        sessionKey: null,
-        sessionId: null,
-      });
-      migrated++;
+    const adapter = resolveAdapter(job);
+    if (!adapter) {
+      try { return markFailure(job, { code: "SCHEDULED_ADAPTER_UNAVAILABLE", message: "Saved channel adapter is unavailable" }); }
+      catch (error) { return { ok: false, status: "failed", error: stableFailure(error) }; }
     }
-    if (migrated > 0) {
-      const backup = `${CRONS_FILE}.migrated`;
-      try { fs.renameSync(CRONS_FILE, backup); } catch (e) {}
-      console.log(`scheduler: migrated ${migrated} legacy cron(s) to jobs.json (backup: ${backup})`);
+    const canonicalUserId = job.canonicalUserId || canonicalForChannel(adapter.type, job.channelId);
+    const userId = String(job.userId || (adapter.type === "telegram" ? job.channelId : canonicalUserId || job.channelId || ""));
+    const chat = {
+      adapter,
+      channelId: String(job.channelId),
+      canonicalUserId,
+      userId,
+      transport: adapter.type,
+      raw: null,
+    };
+
+    return runInChat(chat, async () => {
+      const state = stateForUser(canonicalUserId);
+      if (state.runningProcess || state.preparingRun || state.isCompacting) {
+        try { return markBusy(job); }
+        catch (error) { return { ok: false, status: "failed", error: stableFailure(error) }; }
+      }
+
+      const target = executionTarget(job, state);
+      if (!target) {
+        try {
+          return markFailure(job, {
+            code: "SCHEDULED_PROVIDER_UNAVAILABLE",
+            message: `Saved provider ${job.provider} is unavailable and no explicit fallback is configured`,
+          });
+        } catch (error) { return { ok: false, status: "failed", error: stableFailure(error) }; }
+      }
+
+      const project = projectDescriptor(job);
+      const prompt = wrappedPrompt(job, target);
+      const runOptions = {
+        purpose: "scheduled",
+        provider: target.provider,
+        providerSettings: target.providerSettings,
+        project,
+        fresh: target.fresh,
+        resumeSessionId: target.sessionId || null,
+        attachSession: target.attachSession,
+        requiredDelivery: true,
+        occurrenceId: job.occurrenceId,
+        scheduledJobId: job.id,
+        originRunId: job.originRunId || null,
+      };
+      // Admission is synchronous and precedes all notification delivery.
+      const runContext = admit(prompt, project.dir, null, runOptions);
+
+      let running;
+      try {
+        running = jobsStore.update(job.id, {
+          status: "running",
+          disabled: false,
+          attemptCount: (job.attemptCount || 0) + 1,
+          lastAttemptAt: now(),
+          nextAttemptAt: now() + retryDelayMs,
+          lastProvider: target.provider,
+          fallbackFromProvider: target.fallbackFrom,
+        });
+        if (!running) throw new Error("scheduled attempt could not be persisted");
+      } catch (error) {
+        return { ok: false, status: "failed", error: stableFailure(error) };
+      }
+
+      try { await send(`Wakeup: ${job.label}`); } catch (_) { /* advisory only */ }
+      let result;
+      try { result = await runInProvider(prompt, runContext.cwd, null, { ...runOptions, runContext }); }
+      catch (error) {
+        try { return markFailure(running, error, { attemptAlreadyCounted: true }); }
+        catch (persistError) { return { ok: false, status: "failed", error: stableFailure(persistError) }; }
+      }
+      if (!terminalRunSucceeded(result)) {
+        try { return markFailure(running, result, { attemptAlreadyCounted: true }); }
+        catch (error) { return { ok: false, status: "failed", error: stableFailure(error), result }; }
+      }
+      return settleSuccess(running, result, target);
+    });
+  }
+
+  function scheduleJob(job) {
+    unscheduleJob(job.id);
+    if (!job || job.disabled || ["archived", "dead-letter"].includes(job.status)) return false;
+    if (job.status === "succeeded" && job.kind === "wakeup") {
+      try { jobsStore.remove(job.id); } catch (_) {}
+      return false;
     }
-    return migrated;
-  } catch (e) {
-    console.error("scheduler: legacy migration failed:", e.message);
-    return 0;
+    if (["failed", "deferred", "running"].includes(job.status)) {
+      armRetry(job, Math.max(0, Number(job.nextAttemptAt || now()) - now()));
+      return true;
+    }
+    if (job.kind === "wakeup") {
+      const fireAt = Number(job.fireAt || 0);
+      const overdue = now() - fireAt;
+      if (overdue > missedGraceMs) {
+        try {
+          jobsStore.update(job.id, {
+            status: "dead-letter",
+            disabled: true,
+            nextAttemptAt: null,
+            lastError: { code: "MISSED_WAKEUP_EXPIRED", message: "Wakeup exceeded the missed-fire grace window" },
+          });
+        } catch (_) {}
+        return false;
+      }
+      const timeout = setTimer(() => fireJob(job.id, { reason: fireAt < now() ? "missed" : "timer" }), Math.max(0, fireAt - now()));
+      timers.set(job.id, { timeout });
+      return true;
+    }
+    if (job.kind === "cron") {
+      if (!validateCron(job.schedule)) return false;
+      const task = scheduleCron(job.schedule, () => {
+        const current = jobsStore.get(job.id);
+        if (!current || current.disabled || current.status !== "pending") return;
+        fireJob(current.id, { reason: "cron" });
+      });
+      timers.set(job.id, { stop: () => task.stop?.() });
+      return true;
+    }
+    return false;
   }
-}
 
-function fireMissedWakeupsOnce() {
-  const now = Date.now();
-  for (const job of jobs.listAll()) {
-    if (job.kind !== "wakeup") continue;
-    if (!job.fireAt) continue;
-    if (job.fireAt >= now) continue;
-    if (now - job.fireAt > MISSED_WAKEUP_GRACE_MS) {
-      jobs.remove(job.id);
-      continue;
+  function archiveLegacyCrons() {
+    if (!legacyCronsFile || !fs.existsSync(legacyCronsFile)) return 0;
+    let raw;
+    try { raw = JSON.parse(fs.readFileSync(legacyCronsFile, "utf8")); }
+    catch (_) { return 0; }
+    if (!Array.isArray(raw)) return 0;
+    const existing = new Set([
+      ...jobsStore.listAll().map((job) => job.id),
+      ...(jobsStore.listArchived ? jobsStore.listArchived().map((job) => job.id) : []),
+    ]);
+    let count = 0;
+    for (const legacy of raw) {
+      if (!legacy || !legacy.schedule || !legacy.prompt) continue;
+      const id = legacy.id || `legacy-cron-${crypto.createHash("sha256").update(JSON.stringify(legacy)).digest("hex").slice(0, 16)}`;
+      if (existing.has(id)) continue;
+      jobsStore.archive({ ...legacy, id, kind: "cron" }, "Legacy cron had no saved provider/session identity and is disabled");
+      existing.add(id);
+      count += 1;
     }
-    setTimeout(() => fireJob({ ...job, label: `${job.label || "wakeup"} (missed)` }), 1000);
+    return count;
   }
-}
 
-function initScheduler(adapterList) {
-  setAdapters(adapterList);
-  migrateLegacyCrons();
-  for (const job of jobs.listAll()) {
-    try { scheduleJob(job); }
-    catch (e) { console.error(`scheduler: failed to schedule ${job.id}:`, e.message); }
+  function init() {
+    jobsStore.ensureMigrated?.();
+    archiveLegacyCrons();
+    for (const job of jobsStore.listAll()) scheduleJob(job);
+    return jobsStore.listAll().length;
   }
-  fireMissedWakeupsOnce();
-  console.log(`scheduler: loaded ${jobs.listAll().length} job(s)`);
-}
 
-function addJob(spec) {
-  const job = jobs.add(spec);
-  try { scheduleJob(job); }
-  catch (e) { console.error(`scheduler: failed to schedule new ${job.id}:`, e.message); }
-  return job;
-}
+  function enrichJobSpec(spec) {
+    const state = dependencies.currentState ? dependencies.currentState() : currentState();
+    const provider = spec.provider || getActiveProvider(state);
+    const project = spec.project || getProjectKey(state);
+    const projectDir = spec.projectDir || (state.currentSession?.name === project ? state.currentSession?.dir : null);
+    const sessionId = Object.prototype.hasOwnProperty.call(spec, "sessionId")
+      ? spec.sessionId
+      : getProviderSession(state, provider, project);
+    const originRunId = spec.originRunId || state.activeRunContext?.runId || null;
+    const providerSettings = spec.providerSettings || getProviderSettings(state, provider);
+    return {
+      ...spec,
+      id: spec.id || defaultJobsStore.nextId(spec.kind || "job"),
+      adapter: spec.adapter || dependencies.defaultAdapter || null,
+      adapterType: spec.adapterType || dependencies.defaultAdapterType || null,
+      channelId: spec.channelId == null ? null : String(spec.channelId),
+      canonicalUserId: spec.canonicalUserId || state.userId || null,
+      userId: spec.userId || null,
+      provider,
+      providerSettings: structuredClone(providerSettings || {}),
+      project,
+      projectDir,
+      sessionId: sessionId || null,
+      previousSessionId: spec.previousSessionId || sessionId || null,
+      originRunId,
+      sessionLineage: {
+        ...(spec.sessionLineage || {}),
+        originRunId,
+        originSessionId: spec.sessionLineage?.originSessionId || sessionId || null,
+      },
+      occurrenceId: spec.occurrenceId || occurrenceIdFactory(spec),
+      status: "pending",
+      disabled: false,
+      attemptCount: 0,
+    };
+  }
 
-function removeJob(id) {
-  unscheduleJob(id);
-  return jobs.remove(id);
+  function addJob(spec) {
+    const job = jobsStore.add(enrichJobSpec(spec));
+    scheduleJob(job);
+    return job;
+  }
+
+  function removeJob(id) {
+    unscheduleJob(id);
+    return jobsStore.remove(id);
+  }
+
+  function stopAll() {
+    for (const id of [...timers.keys()]) unscheduleJob(id);
+  }
+
+  return {
+    setAdapters,
+    init,
+    scheduleJob,
+    unscheduleJob,
+    addJob,
+    removeJob,
+    stopAll,
+    fireJob,
+    archiveLegacyCrons,
+    enrichJobSpec,
+    resolveCompactionLineage,
+    timers,
+  };
 }
 
-function stopAll() {
-  for (const [id] of timers) unscheduleJob(id);
+const service = createSchedulerService();
+
+function setAdapters(list) { return service.setAdapters(list); }
+function initScheduler(adapterList) {
+  service.setAdapters(adapterList);
+  const count = service.init();
+  console.log(`scheduler: loaded ${count} job(s)`);
+  return count;
 }
 
 module.exports = {
+  MISSED_WAKEUP_GRACE_MS,
+  RETRY_DELAY_MS,
+  BUSY_DELAY_MS,
+  createSchedulerService,
+  parseFallbacks,
+  terminalRunSucceeded,
   setAdapters,
   initScheduler,
-  scheduleJob,
-  unscheduleJob,
-  addJob,
-  removeJob,
-  stopAll,
-  fireJob,
+  scheduleJob: service.scheduleJob,
+  unscheduleJob: service.unscheduleJob,
+  addJob: service.addJob,
+  removeJob: service.removeJob,
+  stopAll: service.stopAll,
+  fireJob: service.fireJob,
 };