@cohortapp/agent-sdk 2.3.0

package/lib/scheduling/dynamic-jobs.mjs

@@ -0,0 +1,675 @@
+/**
+ * dynamic-jobs.mjs — agent-created one-off and recurring scheduled jobs.
+ *
+ * Why this exists
+ * ---------------
+ * The cadence bus handles the FRAMEWORK's standard cadences (inbox-processor,
+ * morning brief, …). It does not give an agent the everyday-employee primitive:
+ * "remind X this Friday at 9am", "every weekday at 8am summarize the channel".
+ * gaps-product-quality P1-5 calls this out as the missing core: "no
+ * agent-created dynamic jobs (one-shot 'at'/interval/cron with per-job payload —
+ * the core 'remind X Friday 9am' primitive a fleet of employees needs)".
+ *
+ * This module owns that primitive end to end EXCEPT the firing wiring:
+ *   - parseWhen(text)         natural-ish "when" → {at} or {cron} (+ tz)
+ *   - createJob/listJobs/cancelJob   CRUD over state/scheduling/jobs.json
+ *   - dueJobs(now)            which jobs should fire right now
+ *
+ * The daemon / cadence consumer is the thing that calls dueJobs() on its timer
+ * and actually delivers each job's payload — that wiring is a deliberate
+ * follow-up, NOT in this lane. Everything here is pure logic over an injectable
+ * clock and an atomic JSON file, so it is fully unit-testable offline.
+ *
+ * Robustness contract (matches the cadence-bus house idiom)
+ * ---------------------------------------------------------
+ *  - Atomic, durable writes via lib/fs-atomic.mjs (write-temp → fsync →
+ *    rename), so a crash mid-write never corrupts jobs.json.
+ *  - Fail-open reads: an unreadable/corrupt jobs.json reads as an empty store
+ *    rather than throwing, so one bad byte never wedges every job.
+ *  - Consume-time coalescing + TTL: after an outage, a recurring job that
+ *    missed three morning windows fires ONCE on the next due-check (catch up to
+ *    "now", do not replay a burst), and a one-off whose window is older than
+ *    its TTL is skipped (and cancelled) rather than fired stale.
+ *  - notBefore redelivery: dueJobs can mark a job "not before T" (e.g. the
+ *    consumer deferred it under load); it stays invisible until T, so deferred
+ *    jobs do not thrash in a claim→requeue loop.
+ *
+ * Node builtins + lib/fs-atomic only (maestro is near-zero-dep by design).
+ *
+ * @module lib/scheduling/dynamic-jobs
+ */
+
+import { existsSync, readFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { randomBytes } from "node:crypto";
+
+import { writeJsonAtomic } from "../fs-atomic.mjs";
+
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+
+export const JOBS_RELATIVE = "state/scheduling/jobs.json";
+
+/**
+ * Default TTL for a one-off job whose fire window was missed (outage / daemon
+ * down). A one-off due more than this long ago is considered stale: skipped and
+ * cancelled rather than delivered late. 6h is long enough to survive a normal
+ * reboot/outage window but short enough that a "9am reminder" never surfaces at
+ * 6pm. Recurring jobs are never stale (they always re-target the next window) —
+ * the TTL only bounds the one-off / catch-up window.
+ */
+export const DEFAULT_TTL_MS = 6 * 60 * 60 * 1000;
+
+const DAY_MS = 24 * 60 * 60 * 1000;
+
+const WEEKDAYS = [
+  "sunday",
+  "monday",
+  "tuesday",
+  "wednesday",
+  "thursday",
+  "friday",
+  "saturday",
+];
+const WEEKDAY_INDEX = new Map(WEEKDAYS.map((d, i) => [d, i]));
+// Common short forms.
+for (const [k, v] of [
+  ["sun", 0], ["mon", 1], ["tue", 2], ["tues", 2], ["wed", 3],
+  ["thu", 4], ["thur", 4], ["thurs", 4], ["fri", 5], ["sat", 6],
+]) {
+  WEEKDAY_INDEX.set(k, v);
+}
+
+// ---------------------------------------------------------------------------
+// Path resolution
+// ---------------------------------------------------------------------------
+
+/**
+ * Resolve the jobs.json path for an agent root. Mirrors cadence-bus path
+ * resolution: explicit arg, then AGENT_ROOT, then AGENT_DIR, then cwd.
+ * @param {string} [agentRoot]
+ * @returns {string} absolute path to state/scheduling/jobs.json
+ */
+export function getJobsPath(agentRoot) {
+  const root = resolve(
+    agentRoot ||
+      process.env.AGENT_ROOT ||
+      process.env.AGENT_DIR ||
+      process.cwd()
+  );
+  return join(root, JOBS_RELATIVE);
+}
+
+// ---------------------------------------------------------------------------
+// Store I/O (fail-open read, atomic durable write)
+// ---------------------------------------------------------------------------
+
+/**
+ * Read the jobs store. Returns { jobs: [...] }. Fails open: a missing or
+ * corrupt file reads as an empty store rather than throwing — one bad byte must
+ * never wedge every scheduled job.
+ * @param {string} [agentRoot]
+ * @returns {{ jobs: object[] }}
+ */
+export function readStore(agentRoot) {
+  const path = getJobsPath(agentRoot);
+  if (!existsSync(path)) return { jobs: [] };
+  try {
+    const parsed = JSON.parse(readFileSync(path, "utf-8"));
+    if (parsed && Array.isArray(parsed.jobs)) return { jobs: parsed.jobs };
+    return { jobs: [] };
+  } catch {
+    return { jobs: [] };
+  }
+}
+
+/**
+ * Persist the jobs store atomically (write-temp → fsync → rename).
+ * @param {string} agentRoot
+ * @param {{ jobs: object[] }} store
+ * @returns {void}
+ */
+function writeStore(agentRoot, store) {
+  writeJsonAtomic(getJobsPath(agentRoot), { jobs: store.jobs });
+}
+
+/**
+ * Generate a unique, sortable job id: job-<iso>-<hex>.
+ * @param {Date} [now]
+ * @returns {string}
+ */
+export function nextJobId(now = new Date()) {
+  return `job-${now.toISOString()}-${randomBytes(4).toString("hex")}`;
+}
+
+// ---------------------------------------------------------------------------
+// parseWhen — natural-ish "when" → {at} | {cron}
+// ---------------------------------------------------------------------------
+
+/**
+ * Parse a clock phrase like "9am", "8:30am", "14:00", "9 am", "noon",
+ * "midnight" into {hour, minute} (24h). Returns null if no time is present —
+ * callers default to a sensible hour.
+ * @param {string} text
+ * @returns {{hour:number, minute:number}|null}
+ */
+function parseClock(text) {
+  if (/\bnoon\b/.test(text)) return { hour: 12, minute: 0 };
+  if (/\bmidnight\b/.test(text)) return { hour: 0, minute: 0 };
+  // 9am | 9:30am | 9 am | 14:00 | 14h
+  const m = /\b(\d{1,2})(?::(\d{2}))?\s*(am|pm)?\b/.exec(text);
+  if (!m) return null;
+  let hour = Number(m[1]);
+  const minute = m[2] ? Number(m[2]) : 0;
+  const ap = m[3];
+  if (ap === "pm" && hour < 12) hour += 12;
+  if (ap === "am" && hour === 12) hour = 0;
+  if (hour > 23 || minute > 59) return null;
+  return { hour, minute };
+}
+
+/**
+ * Find a weekday name in the text → index 0-6 (Sun=0), or null.
+ * @param {string} text
+ * @returns {number|null}
+ */
+function parseWeekday(text) {
+  for (const [name, idx] of WEEKDAY_INDEX) {
+    if (new RegExp(`\\b${name}\\b`).test(text)) return idx;
+  }
+  return null;
+}
+
+/**
+ * Build a 5-field cron expression (minute hour dom month dow).
+ * @param {string} minute @param {string} hour @param {string} dow
+ * @returns {string}
+ */
+function cron({ minute = "*", hour = "*", dom = "*", month = "*", dow = "*" }) {
+  return `${minute} ${hour} ${dom} ${month} ${dow}`;
+}
+
+/**
+ * Parse a natural-ish scheduling phrase into a concrete schedule descriptor.
+ *
+ * Returns one of:
+ *   { at: <ms epoch>, tz }                — a single future instant (one-off)
+ *   { cron: "<m h dom mon dow>", tz }     — a recurring schedule
+ *
+ * Recognised, in priority order:
+ *   - "in 2 hours" / "in 30 minutes" / "in 3 days"      → one-off relative {at}
+ *   - "every weekday at 8am"                            → cron "0 8 * * 1-5"
+ *   - "every day at 7am" / "daily 7am"                  → cron "0 7 * * *"
+ *   - "every monday 9am" / "every fri 17:00"           → cron "0 9 * * 1"
+ *   - "tomorrow 9am"                                    → one-off {at}
+ *   - "today 5pm" / a bare time "9am"                   → one-off {at} (next
+ *                                                          such instant)
+ *   - "friday 9am" / "next friday 9am"                 → one-off {at} (next
+ *                                                          occurrence of that
+ *                                                          weekday at that time)
+ *
+ * Times with no am/pm and hour < 8 are treated as 24h (so "14:00" works);
+ * a phrase with no recognised time defaults to 09:00 local.
+ *
+ * Timezone: `opts.tz` is recorded on the descriptor and used to resolve
+ * "9am" to the right wall-clock. Defaults to UTC. Returns null if nothing
+ * schedule-like is found (caller can ask the user to rephrase).
+ *
+ * @param {string} text
+ * @param {object} [opts]
+ * @param {Date|number} [opts.now=Date.now()]  injectable clock
+ * @param {string} [opts.tz="UTC"]            IANA tz for local-time resolution
+ * @returns {{at:number, tz:string}|{cron:string, tz:string}|null}
+ */
+export function parseWhen(text, opts = {}) {
+  if (typeof text !== "string" || !text.trim()) return null;
+  const tz = opts.tz || "UTC";
+  const nowMs = opts.now instanceof Date ? opts.now.getTime()
+    : typeof opts.now === "number" ? opts.now
+    : Date.now();
+  const s = text.toLowerCase().trim();
+
+  // --- relative one-off: "in N unit(s)" ------------------------------------
+  const rel = /\bin\s+(\d+)\s*(second|sec|minute|min|hour|hr|day|week)s?\b/.exec(s);
+  if (rel) {
+    const n = Number(rel[1]);
+    const unit = rel[2];
+    const unitMs =
+      unit.startsWith("sec") ? 1000 :
+      unit.startsWith("min") ? 60_000 :
+      unit.startsWith("hour") || unit === "hr" ? 3_600_000 :
+      unit === "week" ? 7 * DAY_MS :
+      DAY_MS; // day
+    return { at: nowMs + n * unitMs, tz };
+  }
+
+  const clock = parseClock(s);
+  const time = clock || { hour: 9, minute: 0 };
+  const recurring = /\bevery\b|\bdaily\b|\beach\b/.test(s);
+
+  // --- recurring → cron ----------------------------------------------------
+  if (recurring) {
+    if (/\bweekday(s)?\b/.test(s)) {
+      return { cron: cron({ minute: String(time.minute), hour: String(time.hour), dow: "1-5" }), tz };
+    }
+    if (/\bweekend(s)?\b/.test(s)) {
+      return { cron: cron({ minute: String(time.minute), hour: String(time.hour), dow: "0,6" }), tz };
+    }
+    const wd = parseWeekday(s);
+    if (wd !== null) {
+      return { cron: cron({ minute: String(time.minute), hour: String(time.hour), dow: String(wd) }), tz };
+    }
+    // "every day" / "daily" / "every morning"
+    return { cron: cron({ minute: String(time.minute), hour: String(time.hour) }), tz };
+  }
+
+  // --- one-off absolute → {at} ---------------------------------------------
+  // "tomorrow", "today", a specific weekday, or a bare time (next occurrence).
+  const local = localPartsAt(nowMs, tz);
+  const wantWeekday = parseWeekday(s);
+
+  if (/\btomorrow\b/.test(s)) {
+    return { at: nextLocalInstant(nowMs, tz, time, { addDays: 1 }), tz };
+  }
+  if (/\btoday\b/.test(s)) {
+    // Today at the given time; if already past, this still resolves to today's
+    // instant (caller's TTL/coalescing decides whether to skip a stale one).
+    return { at: localInstant(local, time, tz), tz };
+  }
+  if (wantWeekday !== null) {
+    return { at: nextWeekdayInstant(nowMs, tz, wantWeekday, time), tz };
+  }
+  if (clock) {
+    // Bare time, e.g. "9am" → the next time it is 9am locally.
+    return { at: nextLocalInstant(nowMs, tz, time), tz };
+  }
+
+  return null;
+}
+
+// ---------------------------------------------------------------------------
+// Local-time arithmetic (tz-aware via Intl, no tz database dependency)
+// ---------------------------------------------------------------------------
+
+/**
+ * Decompose a ms instant into local wall-clock parts for `tz`.
+ * Fails open to UTC parts for an invalid tz.
+ * @returns {{year,month,day,hour,minute,second,weekday}}
+ */
+function localPartsAt(ms, tz) {
+  let dtf;
+  try {
+    dtf = new Intl.DateTimeFormat("en-US", {
+      timeZone: tz,
+      hour12: false,
+      weekday: "short",
+      year: "numeric", month: "2-digit", day: "2-digit",
+      hour: "2-digit", minute: "2-digit", second: "2-digit",
+    });
+  } catch {
+    const d = new Date(ms);
+    return {
+      year: d.getUTCFullYear(), month: d.getUTCMonth() + 1, day: d.getUTCDate(),
+      hour: d.getUTCHours(), minute: d.getUTCMinutes(), second: d.getUTCSeconds(),
+      weekday: d.getUTCDay(),
+    };
+  }
+  const p = {};
+  for (const part of dtf.formatToParts(new Date(ms))) {
+    if (part.type !== "literal") p[part.type] = part.value;
+  }
+  const hour = p.hour === "24" ? 0 : Number(p.hour);
+  const wdShort = String(p.weekday || "").toLowerCase().slice(0, 3);
+  return {
+    year: Number(p.year), month: Number(p.month), day: Number(p.day),
+    hour, minute: Number(p.minute), second: Number(p.second),
+    weekday: WEEKDAY_INDEX.has(wdShort) ? WEEKDAY_INDEX.get(wdShort) : 0,
+  };
+}
+
+/**
+ * Given local Y/M/D parts and a target {hour,minute}, produce the ms-epoch
+ * instant of that local wall-clock time in `tz`. Resolves the tz offset AT the
+ * target so DST is handled. Fails open to UTC.
+ */
+function localInstant(parts, time, tz) {
+  // First guess: interpret the wanted wall-clock as if UTC.
+  const guess = Date.UTC(parts.year, parts.month - 1, parts.day, time.hour, time.minute, 0);
+  // Correct by the tz offset at that guess (offset minutes: UTC + off = local).
+  const offMin = tzOffsetMinutes(tz, guess);
+  return guess - offMin * 60_000;
+}
+
+/**
+ * tz offset in minutes at instant `ms` (UTC + offset = local). Fail-open 0.
+ */
+function tzOffsetMinutes(tz, ms) {
+  let dtf;
+  try {
+    dtf = new Intl.DateTimeFormat("en-US", {
+      timeZone: tz, hour12: false,
+      year: "numeric", month: "2-digit", day: "2-digit",
+      hour: "2-digit", minute: "2-digit", second: "2-digit",
+    });
+  } catch { return 0; }
+  const p = {};
+  for (const part of dtf.formatToParts(new Date(ms))) {
+    if (part.type !== "literal") p[part.type] = part.value;
+  }
+  const hour = p.hour === "24" ? 0 : Number(p.hour);
+  const asUtc = Date.UTC(Number(p.year), Number(p.month) - 1, Number(p.day), hour, Number(p.minute), Number(p.second));
+  return Math.round((asUtc - ms) / 60_000);
+}
+
+/**
+ * The next instant at local `time` in `tz`, strictly after `nowMs`, optionally
+ * forced forward by `addDays`. Used for "tomorrow 9am" and bare "9am".
+ */
+function nextLocalInstant(nowMs, tz, time, { addDays = 0 } = {}) {
+  const base = localPartsAt(nowMs + addDays * DAY_MS, tz);
+  let inst = localInstant(base, time, tz);
+  // If we did not force a day and the computed instant is already past, roll to
+  // the next day.
+  while (inst <= nowMs) {
+    const next = localPartsAt(inst + DAY_MS, tz);
+    inst = localInstant(next, time, tz);
+  }
+  return inst;
+}
+
+/**
+ * The next instant whose local weekday is `targetWeekday` (Sun=0) at local
+ * `time` in `tz`, strictly after `nowMs`.
+ */
+function nextWeekdayInstant(nowMs, tz, targetWeekday, time) {
+  const today = localPartsAt(nowMs, tz);
+  let delta = (targetWeekday - today.weekday + 7) % 7;
+  let candidate = localInstant(localPartsAt(nowMs + delta * DAY_MS, tz), time, tz);
+  // If it's today (delta 0) but already past, jump a full week.
+  if (candidate <= nowMs) {
+    delta += 7;
+    candidate = localInstant(localPartsAt(nowMs + delta * DAY_MS, tz), time, tz);
+  }
+  return candidate;
+}
+
+// ---------------------------------------------------------------------------
+// cron → next fire time
+// ---------------------------------------------------------------------------
+
+/**
+ * Parse one cron field into a membership predicate over [min,max]. Supports
+ * "*", a list "a,b", a range "a-b", and a step "*\/n" / "a-b/n". This is a
+ * deliberately small subset — enough for the schedules parseWhen emits.
+ * @returns {(v:number)=>boolean}
+ */
+function cronFieldMatcher(field, min, max) {
+  if (field === "*") return () => true;
+  const allowed = new Set();
+  for (const part of field.split(",")) {
+    const [rangePart, stepPart] = part.split("/");
+    const step = stepPart ? Number(stepPart) : 1;
+    let lo = min;
+    let hi = max;
+    if (rangePart !== "*") {
+      const r = rangePart.split("-");
+      lo = Number(r[0]);
+      hi = r.length > 1 ? Number(r[1]) : Number(r[0]);
+    }
+    for (let v = lo; v <= hi; v += step) allowed.add(v);
+  }
+  return (v) => allowed.has(v);
+}
+
+/**
+ * Compute the next instant (ms epoch) strictly after `afterMs` that matches a
+ * 5-field cron expression, evaluated in `tz`. Minute-resolution scan bounded to
+ * ~400 days (covers monthly/weekday schedules). Returns null if no match in the
+ * horizon (malformed cron) — fail-open: caller treats null as "not due".
+ *
+ * Exported for testing and for the consumer's next-fire bookkeeping.
+ *
+ * @param {string} expr   "m h dom mon dow"
+ * @param {number} afterMs
+ * @param {string} [tz="UTC"]
+ * @returns {number|null}
+ */
+export function nextCronAfter(expr, afterMs, tz = "UTC") {
+  const fields = String(expr).trim().split(/\s+/);
+  if (fields.length !== 5) return null;
+  const [minF, hourF, domF, monF, dowF] = fields;
+  let mMin, mHour, mDom, mMon, mDow;
+  try {
+    mMin = cronFieldMatcher(minF, 0, 59);
+    mHour = cronFieldMatcher(hourF, 0, 23);
+    mDom = cronFieldMatcher(domF, 1, 31);
+    mMon = cronFieldMatcher(monF, 1, 12);
+    mDow = cronFieldMatcher(dowF, 0, 6);
+  } catch {
+    return null;
+  }
+  // Start at the next whole minute after afterMs.
+  let cursor = Math.floor(afterMs / 60_000) * 60_000 + 60_000;
+  const horizon = afterMs + 400 * DAY_MS;
+  while (cursor <= horizon) {
+    const lp = localPartsAt(cursor, tz);
+    // Standard cron dom/dow OR-semantics: if both restricted, either matches.
+    const domRestricted = domF !== "*";
+    const dowRestricted = dowF !== "*";
+    let dayOk;
+    if (domRestricted && dowRestricted) dayOk = mDom(lp.day) || mDow(lp.weekday);
+    else dayOk = mDom(lp.day) && mDow(lp.weekday);
+    if (mMin(lp.minute) && mHour(lp.hour) && mMon(lp.month) && dayOk) {
+      return cursor;
+    }
+    cursor += 60_000;
+  }
+  return null;
+}
+
+// ---------------------------------------------------------------------------
+// CRUD
+// ---------------------------------------------------------------------------
+
+/**
+ * Create and persist a scheduled job.
+ *
+ * @param {object} input
+ * @param {string} [input.agentRoot]
+ * @param {{at:number,tz?:string}|{cron:string,tz?:string}} input.when
+ *        a parseWhen() result (or equivalent). Required.
+ * @param {string} input.action   handler/route the consumer will invoke
+ *                                 (e.g. "reminder", "channel-summary"). Required.
+ * @param {object} [input.payload] free-form per-job payload handed to the action.
+ * @param {string} [input.tz]      override the tz on `when`.
+ * @param {number} [input.ttlMs]   one-off staleness window (default 6h).
+ * @param {Date|number} [input.now] injectable clock.
+ * @returns {object} the stored job record.
+ */
+export function createJob(input = {}) {
+  const { when, action } = input;
+  if (!when || typeof when !== "object" || (when.at == null && !when.cron)) {
+    throw new Error("createJob: `when` must be a {at} or {cron} descriptor");
+  }
+  if (!action || typeof action !== "string") {
+    throw new Error("createJob: `action` (string) is required");
+  }
+  const now = input.now instanceof Date ? input.now : new Date(typeof input.now === "number" ? input.now : Date.now());
+  const nowMs = now.getTime();
+  const tz = input.tz || when.tz || "UTC";
+
+  const job = {
+    id: nextJobId(now),
+    action,
+    payload: input.payload && typeof input.payload === "object" ? input.payload : {},
+    tz,
+    status: "active",
+    created_at: now.toISOString(),
+    ttl_ms: Number.isFinite(input.ttlMs) && input.ttlMs > 0 ? input.ttlMs : DEFAULT_TTL_MS,
+  };
+
+  if (when.cron) {
+    job.kind = "recurring";
+    job.cron = String(when.cron);
+    // Pre-compute the first fire so dueJobs has a concrete target.
+    job.next_run_at = nextCronAfter(job.cron, nowMs, tz);
+  } else {
+    job.kind = "once";
+    job.next_run_at = Number(when.at);
+  }
+
+  const store = readStore(input.agentRoot);
+  store.jobs.push(job);
+  writeStore(input.agentRoot, store);
+  return job;
+}
+
+/**
+ * List jobs. By default returns only active (non-cancelled, non-done) jobs;
+ * pass { all: true } to include cancelled/completed.
+ * @param {string} [agentRoot]
+ * @param {object} [opts] @param {boolean} [opts.all=false]
+ * @returns {object[]}
+ */
+export function listJobs(agentRoot, opts = {}) {
+  const store = readStore(agentRoot);
+  if (opts.all) return store.jobs.slice();
+  return store.jobs.filter((j) => j.status === "active");
+}
+
+/**
+ * Cancel a job by id. Marks it cancelled (kept for audit) rather than deleting.
+ * Returns true if a matching active job was found and cancelled.
+ * @param {string} agentRoot
+ * @param {string} id
+ * @param {object} [opts] @param {Date|number} [opts.now]
+ * @returns {boolean}
+ */
+export function cancelJob(agentRoot, id, opts = {}) {
+  const store = readStore(agentRoot);
+  const job = store.jobs.find((j) => j.id === id && j.status === "active");
+  if (!job) return false;
+  job.status = "cancelled";
+  job.cancelled_at = isoNow(opts.now);
+  writeStore(agentRoot, store);
+  return true;
+}
+
+/**
+ * Mark a job "do not fire before T". Used by the consumer to defer a job under
+ * load without losing it — it stays invisible to dueJobs until `notBeforeMs`,
+ * so deferred jobs do not thrash a claim→requeue loop. Returns true if updated.
+ * @param {string} agentRoot
+ * @param {string} id
+ * @param {number} notBeforeMs  ms epoch the job becomes eligible again
+ * @returns {boolean}
+ */
+export function deferJob(agentRoot, id, notBeforeMs) {
+  const store = readStore(agentRoot);
+  const job = store.jobs.find((j) => j.id === id && j.status === "active");
+  if (!job) return false;
+  job.not_before = Number(notBeforeMs);
+  writeStore(agentRoot, store);
+  return true;
+}
+
+function isoNow(now) {
+  if (now instanceof Date) return now.toISOString();
+  if (typeof now === "number") return new Date(now).toISOString();
+  return new Date().toISOString();
+}
+
+// ---------------------------------------------------------------------------
+// dueJobs — the firing decision (coalescing + TTL + notBefore)
+// ---------------------------------------------------------------------------
+
+/**
+ * Determine which active jobs should fire at `now`, and ADVANCE the store to
+ * reflect the consume. This is the consume-time coalescing point:
+ *
+ *   - A one-off whose `next_run_at <= now`:
+ *       · if it is within its TTL → returned to fire, then marked done.
+ *       · if it is older than its TTL (stale, e.g. an outage) → SKIPPED and
+ *         cancelled (status "expired"), NOT fired late. No stale "9am reminder
+ *         at 6pm".
+ *   - A recurring job whose `next_run_at <= now`:
+ *       · returned to fire ONCE, then `next_run_at` is fast-forwarded to the
+ *         next future cron boundary after `now`. A three-day outage therefore
+ *         fires the morning job ONCE on recovery and re-targets tomorrow — it
+ *         never replays the whole missed burst.
+ *   - A job with `not_before > now` is invisible (deferred redelivery).
+ *
+ * The write happens whether or not anything fired-and-changed, but only when
+ * something actually changed, to keep the common "nothing due" case write-free.
+ *
+ * @param {string} agentRoot
+ * @param {object} [opts]
+ * @param {Date|number} [opts.now=Date.now()] injectable clock
+ * @returns {object[]} the jobs that should fire now (each with its payload)
+ */
+export function dueJobs(agentRoot, opts = {}) {
+  const nowMs = opts.now instanceof Date ? opts.now.getTime()
+    : typeof opts.now === "number" ? opts.now
+    : Date.now();
+
+  const store = readStore(agentRoot);
+  const fired = [];
+  let changed = false;
+
+  for (const job of store.jobs) {
+    if (job.status !== "active") continue;
+    if (Number.isFinite(job.not_before) && job.not_before > nowMs) continue;
+    const next = Number(job.next_run_at);
+    if (!Number.isFinite(next) || next > nowMs) continue;
+
+    // Once we fire (or expire) we clear any defer marker.
+    if (job.not_before != null) { delete job.not_before; changed = true; }
+
+    if (job.kind === "recurring") {
+      const ttl = Number.isFinite(job.ttl_ms) ? job.ttl_ms : DEFAULT_TTL_MS;
+      const tz = job.tz || "UTC";
+      // Coalesce: collapse every boundary in [next, now] into ONE fire, never
+      // a burst. After an outage there may be several missed windows (Thu/Fri/
+      // Sat 08:00); we represent that single catch-up by the MOST RECENT missed
+      // boundary, then re-target the next future one. Staleness is judged
+      // against that most-recent boundary — so a 3-day outage whose last window
+      // was an hour ago still fires once, while a job whose only missed window
+      // is older than the TTL is silently skipped (and re-targeted).
+      let lastMissed = next;
+      let advanced = nextCronAfter(job.cron, next, tz);
+      while (advanced != null && advanced <= nowMs) {
+        lastMissed = advanced;
+        advanced = nextCronAfter(job.cron, advanced, tz);
+      }
+      if (nowMs - lastMissed <= ttl) {
+        fired.push(job);
+      }
+      if (advanced != null) {
+        job.next_run_at = advanced; // next future boundary after now
+      } else {
+        // Malformed cron or past horizon: stop the job rather than spin.
+        job.status = "expired";
+        job.expired_at = new Date(nowMs).toISOString();
+      }
+      job.last_fired_at = new Date(nowMs).toISOString();
+      changed = true;
+    } else {
+      // one-off
+      const ttl = Number.isFinite(job.ttl_ms) ? job.ttl_ms : DEFAULT_TTL_MS;
+      if (nowMs - next <= ttl) {
+        fired.push(job);
+        job.status = "done";
+        job.fired_at = new Date(nowMs).toISOString();
+      } else {
+        // Stale: window long past. Expire rather than deliver late.
+        job.status = "expired";
+        job.expired_at = new Date(nowMs).toISOString();
+      }
+      changed = true;
+    }
+  }
+
+  if (changed) writeStore(agentRoot, store);
+  return fired;
+}