@fastagent-sh/fastagent 0.21.1 → 0.22.1

package/dist/schedule/scheduler.js

@@ -1,286 +1,312 @@
-/**
- * The scheduler: a time-trigger that fires the agent on each schedule's cron. SINGLE-PROCESS (like all
- * fastagent state today) — a deployment with schedules must keep one machine running, since cron has no
- * external wake-up (`deploy` enforces that). Started/stopped by the serve path (dev/start).
- *
- * Fire model:
- *  - **stable session per schedule** (`schedule:<name>`), so a schedule's turns share one continuing
- *    conversation persisted by the core session store; the scheduler is ZERO-touch on session storage.
- *  - **output is the agent's tools' job** — the scheduler only fires and logs the outcome.
- *  - **durability = catch up ONCE** (`state.ts`): on start, if the next instant after the last fire is
- *    already past (the process was down across it), fire once and advance — not once per missed slot.
- *    lastFired is claimed BEFORE the invoke (at-most-once per slot: a crash mid-turn won't re-fire it;
- *    "a digest late once" beats "twice"). Strict at-least-once (a per-turn WAL) is a later tier.
- */
+/** Resident cron and wake polling. */
+import * as Cause from "effect/Cause";
+import * as Clock from "effect/Clock";
+import * as Effect from "effect/Effect";
 import { SESSION_BUSY_CODE } from "../agent.js";
+import { PortFailure } from "../effect-port.js";
 import { beginWork } from "../channels/busy.js";
 import { log } from "../log.js";
-import { appendRun } from "./audit.js";
 import { nextRun } from "./cron.js";
-import { loadFires, saveFires } from "./state.js";
+import { routineSession } from "./routine.js";
+import { claimSlot, latestFire, settleClaim } from "./state.js";
 import { deferWakeup, takeFirstDueWakeup } from "./wakeups.js";
-/** A schedule's turns share this stable session — a continuing conversation, like the telegram channel's
- *  per-chat session. Derived at RUNTIME from the name (never an authored field). */
-export function scheduleSession(name) {
-    return `schedule:${name}`;
+/**
+ * Account for a claim whose turn never reported. The slot is claimed BEFORE the turn runs and shutdown does not wait
+ * for that turn (see `AgentService.close`), so a restart landing mid-fire leaves a claim that the next boot skips —
+ * the exact silence the history exists to prevent. Settled once, at the next boot, which also makes it idempotent.
+ *
+ * The claim is the ONE record here: it IS the decision, and the outcome is written back into it.
+ *
+ * NOT re-fired: a turn that kills its own process would then replay on every boot. Cron only: a killed wake-up
+ * leaves no claim behind to reconcile (`takeFirstDueWakeup` removes it before the turn starts).
+ *
+ * THE NEWEST CLAIM ONLY. A schedule's loop runs one turn at a time, so a killed process leaves exactly one claim
+ * unsettled — the one it was in. Walking the whole retained window would add nothing a resident process can
+ * produce, and would instead rewrite every claim an OLDER FORMAT left without an outcome, turning a window of runs
+ * that actually succeeded into `interrupted`.
+ *
+ * KNOWN FALSE POSITIVE: a second scheduler booting while the first is mid-turn sees a claim nothing accounts for
+ * YET, and reports it; the first process then overwrites the outcome when its turn settles. Telling them apart needs
+ * the claimer's liveness, which is a lease, not a claim — and the whole point of the claim is that it needs none.
+ */
+function markInterruptedFire(stateRoot, name, fire) {
+    if (fire === undefined || fire.outcome !== undefined)
+        return;
+    log.warn(`[schedule] ${name}: the fire claimed at ${fire.firedAt} never finished — the process stopped mid-turn ` +
+        `and that slot stays skipped (see \`fastagent routine history ${name}\`)`);
+    // `fire.slot` came from a claim file name, which `listClaims` admits only when it round-trips through this same
+    // conversion — so the Date is valid and `settleClaim` writes back the file it was read from. No duration: this
+    // turn was never timed, and the process that could have timed it is gone.
+    settleClaim(stateRoot, name, new Date(fire.slot), "interrupted");
 }
-// A single setTimeout maxes out at ~24.8 days and drifts over long sleeps; cap each wait so a long
-// interval (or a suspended machine) re-checks against the wall clock rather than firing wildly early/late.
-const MAX_WAIT_MS = 6 * 60 * 60 * 1000; // 6h
-// How often to poll the agent's self-scheduled wake-ups (wakeups.ts). A wake fires within this of its
-// due time — fine for "wake me in N minutes"; cheap (reads a small JSON, writes only when one is due).
-const WAKEUP_POLL_MS = 30 * 1000;
-/** Drive ONE turn (a cron fire or a wake-up) and log its outcome. Total — never throws (its callers are
- *  void-scheduled). Output is the agent's tools' job; this only fires and logs. Returns the turn's audit
- *  material — `failed` (details, if it failed), the accumulated `reply` text, `ms` — plus `busy`: whether
- *  it failed specifically because the session was BUSY (the turn never started) — the ONLY replay-safe
- *  reason to re-fire a wake-up; every other outcome is terminal (side effects may have run). Module-level
- *  (not a scheduler closure) so {@link fireScheduleOnce} — the external-clock fire path — shares it. */
-async function runTurn(agent, label, session, prompt) {
-    const startedAt = Date.now();
-    log.info(`[schedule] ${label} firing (session=${session})`);
-    try {
-        let failed;
-        let busy = false;
-        let reply = "";
-        for await (const e of agent.invoke({ session }, { text: prompt })) {
-            if (e.type === "text")
-                reply += e.delta;
-            if (e.type === "failed") {
-                failed = e.details;
-                busy = e.code === SESSION_BUSY_CODE; // structured (SPEC §8), not a details-text match
-            }
-        }
-        if (failed)
-            log.error(`[schedule] ${label} failed (${Date.now() - startedAt}ms): ${failed}`);
-        else
-            log.info(`[schedule] ${label} completed (${Date.now() - startedAt}ms)`);
-        return { busy: failed !== undefined && busy, failed, reply, ms: Date.now() - startedAt };
-    }
-    catch (e) {
-        // invoke shouldn't throw (SPEC MUST 2 turns failures into events), but stay total regardless. A throw
-        // is not the busy case, so don't defer on it.
-        log.error(`[schedule] ${label} errored (${Date.now() - startedAt}ms): ${String(e)}`);
-        return { busy: false, failed: String(e), reply: "", ms: Date.now() - startedAt };
-    }
+/**
+ * The longest a single armed wait sleeps before looking at the wall clock again.
+ *
+ * WHAT IT BUYS, and only this: a wait LONGER than one cap (a daily, weekly or monthly cron) re-reads the wall
+ * clock every 6 hours, so a clock that jumped forward is noticed within that, instead of after the whole
+ * original delay. MEASURED (2026-09-22): the same jump under a wait SHORTER than the cap changes nothing — a
+ * minute cron whose wall clock jumped 10 minutes past its slot still fired at t+51.4s, when its one timer was
+ * always going to. So this is not a resume guarantee and must not be read as one; it bounds lateness for the
+ * long waits at 6 hours.
+ *
+ * NOT about `setTimeout`'s 2^31-1 ms ceiling: `Effect.sleep` already splits a longer delay by itself
+ * (effect/src/internal/effect.ts, `sleepMillis`).
+ */
+const MAX_WAIT_MS = 6 * 60 * 60 * 1000;
+const WAKEUP_POLL_MS = 30_000;
+/**
+ * ONE LINE, ALWAYS: the tail a failure contributes to its log line, as `: <text>`, or nothing when there is none.
+ *
+ * `log.ts` prefixes only the first line, so a newline anywhere in here emits a second line that is byte-for-byte a
+ * real record (`ERROR [schedule] daily failed (1ms): DISK ON FIRE`) — and a failure detail can carry model or
+ * provider text. Folding also keeps the line-oriented consumers — `docker logs`, journald, CloudWatch — reading one
+ * fire as one event.
+ */
+function oneLine(text) {
+    const folded = text.replace(/\s+/g, " ").trim();
+    return folded === "" ? "" : `: ${folded}`;
 }
 /**
- * Fire ONE schedule's turn: claim (persist lastFired BEFORE invoking, so a crash mid-turn does not
- * re-fire on restart), run, audit. Shared by the resident scheduler's timers and the external-clock
- * serving surface (the AgentCore adapter).
+ * The iterator is a Promise port inside an uninterruptible claimed occurrence, including its cleanup.
  *
- * `slot` is the external clock's idempotency key — the cron instant this fire is FOR. External
- * delivery (EventBridge-style) is at-least-once, so a duplicate slot must not double-fire: when
- * lastFired ≥ slot the fire is SKIPPED (at-most-once per slot, same trade as the resident claim —
- * "a digest late once" beats "twice"). The resident scheduler omits `slot`: its timers fire each
- * slot exactly once, so the unconditional claim is already correct.
+ * WHAT THE TURN SAID IS NOT LOGGED. It is already durable: every fire runs in the session named in the line below
+ * (`routine:<name>` for a cron, the asking conversation for a wake-up), and a session is persisted under
+ * EXPORTED for the API path (`POST /run`), which runs the same turn without a claim: it has no occurrence to
+ * claim, because nobody's grid produced it (schedule/run.ts). The resident clock's own claim/run/settle is
+ * {@link fireRoutineOnce}.
  *
- * A state fault while claiming (loadFires/saveFires — both before the invoke, so nothing ran)
- * THROWS: the resident path catches it at its single skip+audit boundary ({@link createScheduler}'s
- * fireThenReArm — skipping rather than firing unclaimed also avoids an infinite catch-up loop on
- * restart), and the external path lets it surface as a failed request (visible in the clock's logs).
+ * `<stateRoot>/sessions/` like any other. Copying the reply into the log would be a second store of the same text,
+ * unstructured, in a stream with a wider audience and a bound that differs per host.
  */
-export async function fireScheduleOnce(opts) {
-    const { agent, stateRoot, schedule: s, slot, now = () => new Date() } = opts;
-    const fires = loadFires(stateRoot);
-    const last = fires[s.name];
-    if (slot && last && new Date(last).getTime() >= slot.getTime()) {
-        const reason = `slot ${slot.toISOString()} already fired (lastFired=${last})`;
-        log.info(`[schedule] ${s.name}: skipping — ${reason}`);
-        return { fired: false, skippedReason: reason, ms: 0 };
-    }
-    // An external delivery claims the cron instant it represents, not its (possibly much later)
-    // delivery time. Otherwise a delayed fire can make the next distinct slot look like a duplicate.
-    fires[s.name] = (slot ?? now()).toISOString();
-    saveFires(stateRoot, fires);
-    const firedAt = now().toISOString();
-    const r = await runTurn(agent, s.name, scheduleSession(s.name), s.prompt);
-    appendRun(stateRoot, {
-        name: s.name,
-        session: scheduleSession(s.name),
-        firedAt,
-        ms: r.ms,
-        outcome: r.failed ? "failed" : "completed",
-        reply: r.failed ? undefined : r.reply,
-        error: r.failed,
+export function runTurn(agent, label, session, prompt) {
+    return Effect.gen(function* () {
+        const clock = yield* Clock.Clock;
+        const startedAt = clock.currentTimeMillisUnsafe();
+        const elapsed = () => clock.currentTimeMillisUnsafe() - startedAt;
+        log.info(`[schedule] ${label} firing (session=${session})`);
+        return yield* Effect.tryPromise({
+            try: async () => {
+                let failed;
+                let busy = false;
+                // The text deltas are iterated and dropped. Accumulating them would be a second copy of what the session
+                // already holds, and no caller here reads it — the outcome is the whole record (docs/design/core.md §8).
+                for await (const e of agent.invoke({ session }, { text: prompt })) {
+                    if (e.type === "failed") {
+                        failed = e.details;
+                        busy = e.code === SESSION_BUSY_CODE;
+                    }
+                }
+                return { busy: failed !== undefined && busy, failed };
+            },
+            catch: (cause) => new PortFailure(cause),
+        }).pipe(Effect.match({
+            onSuccess: (result) => {
+                // BUSY IS NOT A FAILURE, and this line is where that distinction has to land: the claim file and the
+                // route's reply both say `skipped`, but `docker logs` / CloudWatch is the first place anyone looks, and
+                // it kept saying `ERROR … failed: busy`. "The previous turn is still running" and "the model call died"
+                // need different reactions — a session-busy rejection carries `failed` only because that is the SPEC's
+                // one terminal event shape, which is a wire detail, not a verdict.
+                if (result.busy)
+                    log.info(`[schedule] ${label}: occurrence skipped (session busy) (${elapsed()}ms)`);
+                else if (result.failed)
+                    log.error(`[schedule] ${label} failed (${elapsed()}ms)${oneLine(result.failed)}`);
+                else
+                    log.info(`[schedule] ${label} completed (${elapsed()}ms)`);
+                return { ...result, ms: elapsed() };
+            },
+            onFailure: (error) => {
+                // An iterator throw violates SPEC MUST 2 and is never a replay-safe busy rejection.
+                log.error(`[schedule] ${label} errored (${elapsed()}ms)${oneLine(String(error.cause))}`);
+                return { busy: false, failed: String(error.cause), ms: elapsed() };
+            },
+        }));
     });
-    return { fired: true, failed: r.failed, ms: r.ms };
 }
-export function createScheduler({ agent, stateRoot, schedules, now = () => new Date(), externalClock = false, }) {
-    const timers = new Map();
-    let wakeupTimer;
-    let stopped = false;
-    /** The resident fire path — the shared claim+run+audit, without a slot (see {@link fireScheduleOnce}). */
-    async function fire(s) {
-        await fireScheduleOnce({ agent, stateRoot, schedule: s, now });
-    }
-    /**
-     * The woken turn's prompt arrives ENVELOPED: without it the model sees its own instruction as a bare
-     * user message — in a chat session it may answer a "user" who said nothing — and it has no way to know
-     * the wake-up's id (buried in a long-past tool result), which `unwake` needs. Static cron fires stay raw
-     * on purpose: their prompt is the AUTHOR's instruction in a dedicated `schedule:<name>` session, where
-     * every turn is a fire and an envelope would only dilute it.
-     */
-    function wakeEnvelope(w) {
-        const tag = w.cron
-            ? `[wake-up ${w.id} fired — YOUR recurring self-scheduled turn (cron "${w.cron}"${w.tz ? ` ${w.tz}` : ""}), not a user message; unwake({ id: "${w.id}" }) stops it]`
-            : `[wake-up ${w.id} fired — YOUR self-scheduled turn, not a user message]`;
-        return `${tag} ${w.prompt}`;
-    }
-    /**
-     * Fire every due self-scheduled wake-up, ONE at a time (claim → fire → claim next) so a crash loses at
-     * most one occurrence. Each fires back into the session it was set in. Busy handling splits by kind: a
-     * ONE-SHOT that failed because the session was BUSY (`code: session_busy` — the turn never started; the
-     * very case "wake me in 10 min" hits while the user is still chatting) is deferred to the next poll,
-     * bounded, because a dropped one-shot has no "next time"; a RECURRING busy occurrence is skipped
-     * immediately (its claim already advanced the entry — the next occurrence comes by definition). Any
-     * other failure is terminal for that occurrence (the turn ran — re-running risks duplicate side effects).
-     */
-    async function pollWakeups() {
-        for (;;) {
-            if (stopped)
-                break; // stop() must halt an in-flight drain, like it clears the cron timers
-            const w = takeFirstDueWakeup(stateRoot, now());
-            if (!w)
-                break;
-            const label = `wake ${w.id.slice(0, 8)}`;
-            const firedAt = now().toISOString();
-            // A wake turn runs in the BACKGROUND (no open request tracks it) — count it as in-flight work
-            // (busy.ts) so a serving surface that must not idle mid-turn (the AgentCore /ping) sees it.
-            const workDone = beginWork();
-            const r = await runTurn(agent, label, w.session, wakeEnvelope(w)).finally(workDone);
-            // Busy handling differs by kind (busy = the turn never started — replay-safe; every other outcome is
-            // terminal for this occurrence, since a turn that DID start may have run side effects). ONE-SHOT: defer (bounded) — it has no "next time", dropping it
-            // would lose it forever. RECURRING: the claim already ADVANCED the entry to the next instant (see
-            // takeFirstDueWakeup), so a busy occurrence is simply SKIPPED and audited — the next one comes by
-            // definition, and never touching the stored entry here is what keeps unwake/cancel race-free.
-            let kept = false;
-            if (r.busy && !w.cron) {
-                kept = deferWakeup(stateRoot, w, new Date(now().getTime() + WAKEUP_POLL_MS));
-                if (kept)
-                    log.info(`[schedule] ${label}: session busy — retrying next poll`);
-                else
-                    log.error(`[schedule] ${label}: dropped after too many busy retries`);
-            }
-            else if (r.busy && w.cron) {
-                log.error(`[schedule] ${label}: occurrence skipped (session busy); next fires per cron`);
-            }
-            // Audit honesty: `deferred` ONLY when the same occurrence was actually re-scheduled. A busy one-shot
-            // dropped at the ceiling, and a busy recurring occurrence (skipped — its recurrence survives), are
-            // both FINAL for that occurrence → `failed`.
-            appendRun(stateRoot, {
-                name: "wake",
-                session: w.session,
-                firedAt,
+/** Shared resident/external claim → run → settle. */
+export function fireRoutineOnce(opts) {
+    return Effect.gen(function* () {
+        const clock = yield* Clock.Clock;
+        const { agent, stateRoot, routine: s, slot, now = () => new Date(clock.currentTimeMillisUnsafe()) } = opts;
+        const firedAt = now();
+        const skippedReason = yield* Effect.try({
+            try: () => {
+                // The DECISION to fire is the claim, and it is atomic: several schedulers over one state root — two
+                // `start`s, a restart overlapping its predecessor, an external clock racing the resident one — take the
+                // same slot, and exactly one of them runs it. It is also the ONLY state write on this path, so a state
+                // failure cannot burn a slot that was already claimed.
+                const claim = claimSlot(stateRoot, s.name, slot, firedAt);
+                if (claim.taken)
+                    return undefined;
+                if (claim.why === "duplicate") {
+                    // Ordinary: the same delivery arrived twice, or another scheduler has this slot and is running it.
+                    const reason = `slot ${slot.toISOString()} is already claimed — a duplicate delivery, or another scheduler has it`;
+                    log.info(`[schedule] ${s.name}: skipping — ${reason}`);
+                    return reason;
+                }
+                // Not ordinary: this instant will never run. The common way in is a wall clock that moved backwards (a VM
+                // resume, a host clock correction), which keeps producing slots behind the newest claim. No claim was taken,
+                // so there is nothing to record: it is a WARN where the benign duplicate is an info line.
+                const reason = `slot ${slot.toISOString()} is stale: ${claim.newest} was already claimed, so this instant is skipped`;
+                log.warn(`[schedule] ${s.name}: skipping — ${reason}`);
+                return reason;
+            },
+            catch: (cause) => new PortFailure(cause),
+        });
+        if (skippedReason !== undefined)
+            return { fired: false, skippedReason, ms: 0 };
+        const r = yield* runTurn(agent, s.name, routineSession(s.name), s.prompt);
+        // OVERLAP IS NOT FAILURE. The claim still stands — this occurrence is decided and will not be retried — but
+        // what decided it was the previous turn still holding `routine:<name>`, which is the policy every scheduler
+        // names (k8s `concurrencyPolicy: Forbid`, Temporal's `Skip`) and none of them reports as an error.
+        if (r.busy) {
+            settleClaim(stateRoot, s.name, slot, "skipped", r.ms);
+            return {
+                fired: false,
+                skippedReason: `the previous turn of "${s.name}" is still running — this occurrence is skipped, the next fires per cron`,
+                skipped: true,
                 ms: r.ms,
-                outcome: r.busy ? (kept ? "deferred" : "failed") : r.failed ? "failed" : "completed",
-                reply: r.failed || r.busy ? undefined : r.reply,
-                error: r.busy
-                    ? kept
-                        ? undefined
-                        : w.cron
-                            ? "occurrence skipped (session busy); the recurrence continues"
-                            : "dropped after too many busy retries"
-                    : r.failed,
-            });
-        }
-    }
-    /** Drain due wake-ups, then chain the next poll AFTER — never overlapping two drains. TOTAL: a state-IO
-     *  fault (an unreadable store) is caught + logged and the chain continues, never a crash / a silent stop
-     *  (this is `void`-scheduled, so an escaping throw would be an unhandled rejection). */
-    async function pumpWakeups() {
-        if (stopped)
-            return;
-        try {
-            await pollWakeups();
-        }
-        catch (e) {
-            log.error(`[schedule] wake-up poll failed (continuing next poll): ${String(e)}`);
-        }
-        if (stopped)
-            return;
-        wakeupTimer = setTimeout(() => void pumpWakeups(), WAKEUP_POLL_MS);
-    }
-    /** Arm a timer for `at`, capped so a long wait re-checks the wall clock instead of trusting one sleep. */
-    function arm(s, at) {
-        if (stopped)
-            return;
-        const delay = Math.min(Math.max(0, at.getTime() - now().getTime()), MAX_WAIT_MS);
-        timers.set(s.name, setTimeout(() => {
-            if (stopped)
-                return;
-            if (now().getTime() >= at.getTime())
-                void fireThenReArm(s);
-            else
-                arm(s, at); // woke early (the cap) — keep waiting for the real instant
-        }, delay));
-    }
-    /** Fire, then arm the NEXT run computed from now — so a slow fire never double-fires the same slot and
-     *  missed slots collapse to the single catch-up already done. TOTAL, like pumpWakeups: this is
-     *  void-scheduled from a timer, so an escaping throw (a state-IO fault while claiming — an unreadable
-     *  fires.json, an unpersistable claim) would be an unhandled rejection = the WHOLE service crashing over
-     *  one skipped fire. Log it and keep the schedule armed instead; boot-time state faults still fail `start()`
-     *  loudly (an operator fixes those before serving). */
-    async function fireThenReArm(s) {
-        try {
-            await fire(s);
+            };
         }
-        catch (e) {
-            // Audited too (appendRun is total, and runs.jsonl ≠ the broken state file) — a skipped fire must
-            // show up in `schedule history`, not only in stderr.
-            log.error(`[schedule] ${s.name}: fire failed (skipping this run, schedule stays armed): ${String(e)}`);
-            appendRun(stateRoot, {
-                name: s.name,
-                session: scheduleSession(s.name),
-                firedAt: now().toISOString(),
-                ms: 0,
-                outcome: "failed",
-                error: `run skipped — fire failed: ${String(e)}`,
+        settleClaim(stateRoot, s.name, slot, r.failed ? "failed" : "completed", r.ms);
+        return { fired: true, failed: r.failed, ms: r.ms };
+    }).pipe(Effect.uninterruptible);
+}
+/** Wakes re-enter a chat session; identify the agent's own instruction and its cancellation handle. */
+function wakeEnvelope(w) {
+    const tag = w.cron
+        ? `[wake-up ${w.id} fired — YOUR recurring self-scheduled turn (cron "${w.cron}"${w.tz ? ` ${w.tz}` : ""}), not a user message; unwake({ id: "${w.id}" }) stops it]`
+        : `[wake-up ${w.id} fired — YOUR self-scheduled turn, not a user message]`;
+    return `${tag} ${w.prompt}`;
+}
+export function createScheduler(options) {
+    return Effect.gen(function* () {
+        const clock = yield* Clock.Clock;
+        const fork = Effect.runForkWith(yield* Effect.context());
+        const { agent, stateRoot, routines, now = () => new Date(clock.currentTimeMillisUnsafe()), externalClock = false, } = options;
+        const loops = new Set();
+        let stopped = false;
+        const launch = (label, work) => {
+            fork(Effect.withFiber((fiber) => {
+                // Publish ownership before a synchronous invoke callback can re-enter stop().
+                loops.add(fiber);
+                return work.pipe(Effect.catchCause((cause) => Effect.sync(() => {
+                    if (!Cause.hasInterruptsOnly(cause))
+                        log.error(`[schedule] ${label}: stopped unexpectedly: ${String(Cause.squash(cause))}`);
+                })), Effect.ensuring(Effect.sync(() => {
+                    loops.delete(fiber);
+                })));
+            }));
+        };
+        const cronLoop = (s, first) => Effect.gen(function* () {
+            let due = first;
+            while (due) {
+                // SLEEP, THEN LOOK AGAIN, in both directions: forward, a jumped clock is noticed a cap early
+                // ({@link MAX_WAIT_MS}); backward — an NTP correction, a VM restored from a snapshot — waking on the
+                // timer alone would fire a slot that has not arrived yet and CLAIM it, burning an occurrence that was
+                // still ahead.
+                while (now().getTime() < due.getTime()) {
+                    yield* Effect.sleep(Math.min(due.getTime() - now().getTime(), MAX_WAIT_MS));
+                }
+                // `slot: due` is what two schedulers have in common: both compute the same cron instant, so both try to
+                // claim the same name and exactly one wins. Claiming `now()` would give them different names.
+                yield* fireRoutineOnce({ agent, stateRoot, routine: s, slot: due, now }).pipe(Effect.catchTag("PortFailure", (error) => Effect.sync(() => {
+                    // Nothing to record: this fault happens BEFORE the claim exists (that is what keeps the slot
+                    // unburned), so there is no claim to write an outcome into.
+                    log.error(`[schedule] ${s.name}: fire failed (skipping this run, schedule stays armed): ${String(error.cause)}`);
+                })), Effect.uninterruptible);
+                due = s.cron === undefined ? undefined : nextRun(s.cron, s.tz, now());
+            }
+        });
+        const wakeOnce = Effect.gen(function* () {
+            const w = yield* Effect.try({
+                try: () => takeFirstDueWakeup(stateRoot, now()),
+                catch: (cause) => new PortFailure(cause),
             });
-        }
-        const due = nextRun(s.cron, s.tz, now());
-        if (due)
-            arm(s, due);
-    }
-    return {
-        start() {
-            stopped = false;
-            // External-clock mode: no cron timers, no boot catch-up — slot delivery (including instants
-            // that passed while this process was down) belongs to the external clock; only the wake-up
-            // pump below runs. See SchedulerOptions.externalClock.
-            const fires = externalClock ? {} : loadFires(stateRoot);
-            const current = now();
-            for (const s of externalClock ? [] : schedules) {
-                // Anchor on the last fire (catch-up basis), or `now` on a first-ever run so a brand-new schedule
-                // never back-fires before the process first booted.
-                const lastFired = fires[s.name];
-                const anchor = lastFired ? new Date(lastFired) : current;
-                const due = nextRun(s.cron, s.tz, anchor);
-                if (!due) {
-                    log.warn(`[schedule] ${s.name}: cron "${s.cron}" will never fire again — not armed`);
-                    continue;
+            if (!w)
+                return false;
+            yield* Effect.acquireUseRelease(Effect.sync(beginWork), () => Effect.gen(function* () {
+                const label = `wake ${w.id.slice(0, 8)}`;
+                const r = yield* runTurn(agent, label, w.session, wakeEnvelope(w));
+                let kept = false;
+                if (r.busy && !w.cron) {
+                    kept = yield* Effect.try({
+                        try: () => deferWakeup(stateRoot, w, new Date(now().getTime() + WAKEUP_POLL_MS)),
+                        catch: (cause) => new PortFailure(cause),
+                    });
+                    if (kept)
+                        log.info(`[schedule] ${label}: session busy — retrying next poll`);
+                    else
+                        log.error(`[schedule] ${label}: dropped after too many busy retries`);
                 }
-                if (due.getTime() <= current.getTime()) {
-                    log.info(`[schedule] ${s.name}: catching up a missed run`);
-                    void fireThenReArm(s); // overdue → fire once, then arm the next
+                else if (r.busy && w.cron) {
+                    // `runTurn` already said it was skipped for a busy session; this adds the one thing it cannot know —
+                    // that a recurring wake has a next occurrence, so nothing is deferred and nothing is lost.
+                    log.info(`[schedule] ${label}: next fires per cron`);
                 }
-                else {
-                    arm(s, due);
+                // A wake-up has no claim to settle (it is removed from the store before the turn starts), so its whole
+                // record is the log lines above and `runTurn`'s — deferred, dropped, failed, completed.
+            }), (done) => Effect.sync(done));
+            return true;
+        }).pipe(
+        // Log storage faults before a pending stop can replace the typed failure with interruption.
+        Effect.catchTag("PortFailure", (error) => Effect.sync(() => {
+            log.error(`[schedule] wake-up poll failed (continuing next poll): ${String(error.cause)}`);
+            return false;
+        })), Effect.uninterruptible);
+        const wakeLoop = Effect.gen(function* () {
+            for (;;) {
+                while (yield* wakeOnce) {
+                    // Claim only after the preceding occurrence settles.
                 }
+                yield* Effect.sleep(WAKEUP_POLL_MS);
             }
-            // Self-scheduled wake-ups: drain now (catch any overdue while the process was down), then chain the
-            // next poll AFTER this drain finishes — a CHAIN, not setInterval, so a wake turn longer than the poll
-            // interval never overlaps two drains (which would break the one-at-a-time claim→fire→claim promise).
-            void pumpWakeups();
-        },
-        stop() {
-            stopped = true;
-            for (const t of timers.values())
-                clearTimeout(t);
-            timers.clear();
-            if (wakeupTimer)
-                clearTimeout(wakeupTimer);
-            wakeupTimer = undefined;
-        },
-    };
+        });
+        return {
+            start() {
+                stopped = false;
+                // ONE claim read per schedule — the newest — for the two planes that must agree about it: the reconciler
+                // (was that fire ever reported?) and catch-up (where does the next run resume?). A read fault on it stays
+                // synchronous, before any timers or turns are started: a schedule whose newest claim cannot be read is not
+                // one to run blind, it is a boot failure. The rest of the window is history, and history does not gate a
+                // boot (`latestFire`).
+                const lastFires = new Map();
+                if (!externalClock) {
+                    for (const s of routines) {
+                        const fire = latestFire(stateRoot, s.name);
+                        if (fire !== undefined)
+                            lastFires.set(s.name, fire.firedAt);
+                        markInterruptedFire(stateRoot, s.name, fire);
+                    }
+                }
+                const current = now();
+                for (const s of externalClock ? [] : routines) {
+                    if (stopped)
+                        break;
+                    // NO CRON, NO CLOCK. A routine without one is not unscheduled by accident — it is reached by name
+                    // (`POST /run`, `fastagent routine run`), so there is nothing here to arm and nothing to warn about.
+                    if (s.cron === undefined)
+                        continue;
+                    // FROM THE LAST FIRE, or from now when there was none. A routine that has never fired does not catch
+                    // up the occurrence it missed while the process was down: nothing recorded that it was ever armed then,
+                    // so "missed" is not a fact this process has. Every boot after the first resumes from the claim.
+                    const last = lastFires.get(s.name);
+                    const due = nextRun(s.cron, s.tz, last ? new Date(last) : current);
+                    if (!due) {
+                        log.warn(`[schedule] ${s.name}: cron "${s.cron}" will never fire again — not armed`);
+                        continue;
+                    }
+                    if (due.getTime() <= current.getTime())
+                        log.info(`[schedule] ${s.name}: catching up a missed run`);
+                    launch(s.name, cronLoop(s, due));
+                }
+                if (!stopped)
+                    launch("wake-up poll", wakeLoop);
+            },
+            stop() {
+                stopped = true;
+                for (const loop of loops)
+                    loop.interruptUnsafe();
+            },
+        };
+    });
 }