Monitoring is periodic. Give the schedule a plane to live on.

An agent whose whole value is noticing — a weekly rank check, a daily anomaly sweep, a digest — has nowhere to say "again next week". The durable execution plane runs a job once; it has no verb for time. The recurrence plane adds exactly that verb: a host registers a schedule, the plane fans it out across tenants and enqueues an agent run at-most-once per occurrence, and one authenticated cron route drives all of it. Wire no schedules and your deployment is byte-identical — the table, the plane and the route are all opt-in.

A schedule is a cadence plus a fan-out plus a terminal. The cadence is a 5-field cron or a fixed everyMs interval (exactly one; declaring both, or neither, throws at registration). The terminal is one of two mutually exclusive shapes, and the type system enforces the choice:

They are exclusive at the type level on purpose: one shape for both is how the first draft got its context wrong. A run(ctx) closure cannot construct a SwarmContext, so an agent schedule written in the run shape could never reach the enqueue gate at all.

The cadence is the timer; the bindings are the fan-out. Each binding becomes one occurrence per fire, keyed on (scheduleId, tenantId, bindingId, scheduledFor, kind). Registering the same id again replaces the definition rather than duplicating it.

import type { ScheduleDef } from "@nightowlsdev/runner-background";

// One weekly rank check, fanned out to two tenants. The cadence is the timer;
// the bindings are the fan-out — one occurrence row per (tenant, binding, instant).
export const weeklyRankCheck: ScheduleDef = {
  id: "seo.weekly-rank-check",     // re-registering this id REPLACES, never duplicates
  cron: "0 9 * * 1",               // 09:00 every Monday...
  timezone: "Europe/London",       // ...in THIS zone. A cron with no zone is a DST bug waiting for October.
  jitterMs: 30_000,                // spread the fan-out so N tenants do not hit one API in the same second
  overrun: "skip",                 // if last week's run is still going, do not start a second
  catchUp: "skip-missed",          // came up late? fire only if still fresh, never replay a backlog
  agent: {
    bindings: [
      {
        bindingId: "acme",
        tenantId: "org_acme",
        ownerUserId: "user_acme_owner", // the REAL user whose rail the run lands in — no synthetic actor
        agentSlug: "seo-researcher",
        message: "Run this week's rank check and flag any position drop over 3.",
        delivery: { mode: "new_thread" },
      },
      {
        bindingId: "globex",
        tenantId: "org_globex",
        ownerUserId: "user_globex_owner",
        agentSlug: "seo-researcher",
        message: "Run this week's rank check and flag any position drop over 3.",
        delivery: { mode: "new_thread" },
      },
    ],
  },
};

bindings can be a resolver () => Promise<ScheduleBinding[]> instead of a static array, which is how multi-tenant fan-out reads its tenant set from the database at tick time. Every resolved set is snapshot-validated on every tick — duplicate (tenantId, bindingId) pairs, empty values, or a reserved params.schedule key fail that schedule's whole tick contribution and claim nothing, rather than letting some bindings fire while others silently collide on one row.

// The OTHER terminal: a plain closure, for framework housekeeping that has no user and no agent.
// A run: schedule gets no SwarmContext and never touches the enqueue gate.
const sessionSweep: ScheduleDef = {
  id: "mcp.session-cleanup",
  everyMs: 15 * 60_000,            // XOR with cron — declaring both, or neither, throws at registration
  // Size this ABOVE the closure's worst-case runtime, or the row reconciles to stale-claim
  // while the closure is still running and the next occurrence starts beside it (window W3).
  staleClaimAfter: "PT2M",
  tenants: ["org_acme", "org_globex"],   // optional fan-out; omit for one tenantless unit
  run: async ({ tenantId, scheduledFor }) => {
    await cleanupExpiredSessions(tenantId, scheduledFor);
  },
};

A timer that fires once is a wish. Vercel Cron and Trigger schedules can both double-fire, so at-most-once cannot rest on hope — it rests on a row. The plane holds an OccurrenceLedger interface and the host injects an implementation: the shipped Postgres one over storage-supabase migration 0031 (nightowls.schedule_occurrences), or the exported in-memory one for tests and dev.

// The occurrence KEY. Five columns, all in the primary key — the claim IS the insert,
// so the key is the entire at-most-once mechanism.
type OccurrenceKey = {
  scheduleId: string;
  tenantId: string;
  bindingId: string;
  scheduledFor: string;             // the resolved canonical UTC instant of this fire
  kind: "scheduled" | "manual";     // a manual triggerNow at the same instant is a DIFFERENT key
};

// The row walks a state machine, and "open" is not a value — it is the ABSENCE of an outcome:
//   scheduled:  claimed -> prepared(runId) -> enqueued -> terminal("ok" | "failed" | "skipped")
//   run:        claimed -------------------------------> terminal
// Every transition is a conditional single statement gated on "outcome IS NULL", returning a
// boolean: did THIS call win? A producer that lost to a stale-reconciling replica stops before
// it enqueues anything. That is the prepare-fence.

To claim is to insert the key; the primary key arbitrates. A second insert of the same key — a double-fired cron, a racing replica, the same host's next tick after a crash — hits on conflict do nothing and loses. That is why at-most-once per occurrence key is absolute: no timeline fires one key twice.

A tick resolves the current occurrence, checks two gates, and either fires or records why it did not. catchUp decides what a late start does: skip-missed (default) is fresh-only — the occurrence fires only while now ≤ due + lateGrace (PT10M by default), so a host that was down for three days does not send a three-day-old digest at breakfast on the fourth. A resume staler than the grace window produces zero fires, not one. A host that wants the stale one asks for it: run-once, or a longer lateGrace. Older-than-current occurrences never fire under either policy.

overrun decides what happens when the previous occurrence is still going: skip (default) or queue. "Still going" is read through the runOutcome oracle, and the counter-intuitive case is the one the reaper-migration proves: a suspended HITL run reads as running. A parked approval ask is alive, and starting a second copy of a weekly sweep while the first waits on a human is exactly what this gate exists to prevent.

A scheduled agent run is not special-cased. The plane builds a trusted SwarmContext server-side from the binding — tenantId, userId from ownerUserId, agentSlug, a fresh or existing threadId from delivery, the minted runId, and audiences, and orgScope — and passes it through the same createBackgroundRunner gate every run uses (agents.head + callerMayReach + enqueueRun).

Two consequences follow. There is no synthetic actor: the run belongs to ownerUserId, a real person, because a system:* user's runs appear in nobody's list. And a binding's audiences is enforced, not advisory — omitted means unrestricted (the framework's universal default), and set means this binding can only reach agent heads within that audience. Its orgScope is the second axis and works the same way: omitted means org-level, so the run mints a NULL-scoped thread that every scope in the tenant can read — set it to mint the thread inside a scope instead. It applies to new_thread delivery only, and is rejected at validation alongside existing_thread, where the target thread's own scope is already authoritative. The binding's params ride in context beneath a trusted schedule triple the plane stamps and the binding cannot forge.

The plane is a pure function of its injected clock and ledger; it carries no timer. A platform cron drives it over one authenticated route, and because the plane fans out internally, a host stops needing one cron entry per periodic feature.

import {
  createSchedulePlane,
  createPgOccurrenceLedger,
  createRunOutcome,
  reaperSchedule,
  type EnqueueAgentRun,
} from "@nightowlsdev/runner-background";
import { createScheduleHandler } from "@nightowlsdev/runner-nextjs";
import type { RunStatus } from "@nightowlsdev/core";

// Host-owned. `enqueueAgentRun` is your background runner's own enqueue seam:
//   const enqueueAgentRun = (input, ctx) => runner.enqueue(input, ctx);
declare const pool: import("pg").Pool;
declare const enqueueAgentRun: EnqueueAgentRun;
declare const storage: { runs: { get(tenantId: string, runId: string): Promise<{ status: RunStatus } | null> } };
declare const reap: () => Promise<number>;
declare const cronSecret: string;

// The plane has ZERO runtime deps: the ledger, the enqueue seam and the run-outcome oracle
// are all injected. There is no timer in here — the host drives ticks from the route below.
const plane = createSchedulePlane({
  ledger: createPgOccurrenceLedger({ pool }),      // over storage-supabase migration 0031
  enqueueAgentRun,
  runOutcome: createRunOutcome(storage),           // maps run status; suspended reads as "running"
  schedules: [reaperSchedule({ reap })],           // the reaper, migrated onto the plane
});

// ONE ROUTE, EVERY SCHEDULE. Point Vercel Cron / GitHub Actions / any pinger at this GET.
export const { GET } = createScheduleHandler({ tick: () => plane.tick(), cronSecret });

reaperSchedule is the first of the framework's cron-delegating features to move onto the plane, and the reason it comes first: it is in-package, idempotent, and already ships both a route and an interval, so migrating it exercises the run: terminal at zero blast radius. A host that wires no schedules keeps startReaper behaving byte-identically.

triggerNow is the explicit operator re-fire, for testing and for "run it now". It targets a whole schedule, one tenant's units, or a single binding (a bindingId without a tenantId throws — a binding is only unique within a tenant).

// The explicit operator re-fire. Bypasses quiescence, enabled, catch-up, overrun and throttle,
// so N invocations are N runs BY DESIGN (window W2) — but it still claims, so a same-instant
// double loses one claim. It also reaches DISABLED schedules and bindings.
await plane.triggerNow({ scheduleId: "seo.weekly-rank-check" });                 // all current units
await plane.triggerNow({ scheduleId: "seo.weekly-rank-check", tenantId: "org_acme" }); // one tenant's units
// -> { fired, failed, duplicate }

A manual fire claims with kind: "manual" and scheduledFor set to the invocation instant, so it is a distinct key from any scheduled fire at the same moment and both stay separately attributable in the ledger. Being an override, it reaches disabled schedules and disabled bindings.

• ScheduleDef: the definition, with its two mutually-exclusive terminals (agent / run) and its per-schedule overrun, catchUp, lateGrace and staleClaimAfter knobs. From @nightowlsdev/runner-background.
• createSchedulePlane(opts) returns { tick, triggerNow, register, listSchedules }. Zero runtime deps — ledger, enqueue seam, run-outcome oracle, clock and rate limit are injected. runScheduleTick is the one-shot sugar.
• OccurrenceLedger + createInMemoryOccurrenceLedger (tests/dev) + createPgOccurrenceLedger({ pool }) over migration 0031.
• createRunOutcome(source) / mapRunStatus: the canonical run-status mapping, with running and suspended both reading as "running".
• reaperSchedule({ reap }): the stuck-run watchdog as a run: schedule — the reference for the one-cron-route pattern.
• createScheduleHandler({ tick, cronSecret }) from @nightowlsdev/runner-nextjs returns { GET }: Bearer-authenticated, no-store, returns the tick's counters.