@fastagent-sh/fastagent 0.24.4 → 0.25.0

package/dist/schedule/scheduler.js

@@ -1,44 +1,18 @@
 /** Resident cron and wake polling. */
 import * as Cause from "effect/Cause";
 import * as Clock from "effect/Clock";
+import * as Deferred from "effect/Deferred";
+import * as Result from "effect/Result";
 import * as Effect from "effect/Effect";
-import { SESSION_BUSY_CODE } from "../agent.js";
+import { join } from "node:path";
+import { AgentError } from "../agent-api.js";
+import { conversationSessions } from "../conversation-sessions.js";
 import { PortFailure } from "../effect-port.js";
 import { beginWork } from "../channels/busy.js";
 import { log } from "../log.js";
 import { nextRun } from "./cron.js";
-import { routineSession } from "./routine.js";
 import { claimSlot, latestFire, settleClaim } from "./state.js";
-import { deferWakeup, takeFirstDueWakeup } from "./wakeups.js";
-/**
- * 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");
-}
+import { requeueWakeup, takeFirstDueWakeup } from "./wakeups.js";
 /**
  * The longest a single armed wait sleeps before looking at the wall clock again.
  *
@@ -66,67 +40,94 @@ function oneLine(text) {
     const folded = text.replace(/\s+/g, " ").trim();
     return folded === "" ? "" : `: ${folded}`;
 }
+/** What a wait for a message's end gave instead of its end, as the one line this log says it with. */
+async function untilEnded(agent, key, signal) {
+    return agent.messages.get(key, { wait: Number.POSITIVE_INFINITY, signal }).then((message) => ({ ended: message }), (error) => ({
+        unfinished: `waiting for its end failed: ${error instanceof Error ? error.message : String(error)}`,
+    }));
+}
 /**
- * The iterator is a Promise port inside an uninterruptible claimed occurrence, including its cleanup.
- *
- * 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}.
+ * Send one message and wait for its end; `onAccepted` hears that it was recorded. Interrupted, it stops waiting, and
+ * the agent goes on: a Caller that stops waiting only lets go (SPEC.md §4).
+ */
+async function sendAndWait(agent, request, onAccepted, signal) {
+    let message;
+    try {
+        message = await agent.messages.send(request);
+    }
+    catch (error) {
+        if (!(error instanceof AgentError))
+            throw error;
+        if (error.code === "unconfirmed")
+            return { unfinished: `whether it was recorded is not known: ${error.message}` };
+        return { refused: error.message, busy: error.code === "busy" };
+    }
+    onAccepted();
+    return untilEnded(agent, { sessionId: message.sessionId, messageId: message.id }, signal);
+}
+/** How a message ended, as the one word a claim keeps, and the detail worth a log line. */
+function settled(message) {
+    switch (message.status) {
+        case "completed":
+        case "incomplete":
+            return { fire: "completed" };
+        case "canceled":
+            return { fire: "failed", detail: "canceled" };
+        default:
+            return { fire: "failed", detail: message.error?.message ?? `the message ended ${message.status}` };
+    }
+}
+/**
+ * One invoke, read to its message's end, with what became of it said in the log.
  *
- * `<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.
+ * WHAT THE AGENT SAID IS NOT LOGGED. It is already durable: every fire runs in the session named in the line below
+ * (the schedule's own, the asking conversation's for a wake-up), kept in the instance's storage 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 function runTurn(agent, label, session, prompt) {
+function runTurn(agent, label, request, onAccepted = () => { }) {
     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 };
-            },
+        log.info(`[schedule] ${label} firing (session=${request.sessionId})`);
+        const read = yield* Effect.tryPromise({
+            try: (signal) => sendAndWait(agent, request, onAccepted, signal),
             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() };
-            },
-        }));
+        }).pipe(Effect.result);
+        const ms = elapsed();
+        if (Result.isFailure(read)) {
+            // Not an AgentError: a fault of the agent's, so this fire's failure, never a refusal.
+            const failed = String(read.failure.cause);
+            log.error(`[schedule] ${label} errored (${ms}ms)${oneLine(failed)}`);
+            return { fire: "failed", busy: false, failed, ms };
+        }
+        const end = read.success;
+        if ("unfinished" in end) {
+            log.error(`[schedule] ${label} failed (${ms}ms)${oneLine(end.unfinished)}`);
+            return { fire: "failed", busy: false, failed: end.unfinished, ms };
+        }
+        if ("refused" in end) {
+            // BUSY IS NOT A FAILURE: "the previous run is still going" and "the model call died" need different reactions.
+            if (end.busy)
+                log.info(`[schedule] ${label}: occurrence skipped (session busy) (${ms}ms)`);
+            else
+                log.error(`[schedule] ${label} refused (${ms}ms)${oneLine(end.refused)}`);
+            return { fire: "failed", busy: end.busy, failed: end.refused, ms };
+        }
+        const { fire, detail } = settled(end.ended);
+        if (fire === "completed")
+            log.info(`[schedule] ${label} completed (${ms}ms)`);
+        else
+            log.error(`[schedule] ${label} ${fire} (${ms}ms)${oneLine(detail ?? "")}`);
+        return { fire, busy: false, failed: fire === "completed" ? undefined : detail, ms };
     });
 }
 /** Shared resident/external claim → run → settle. */
-export function fireRoutineOnce(opts) {
+export function fireScheduleOnce(opts) {
     return Effect.gen(function* () {
         const clock = yield* Clock.Clock;
-        const { agent, stateRoot, routine: s, slot, now = () => new Date(clock.currentTimeMillisUnsafe()) } = opts;
+        const { agent, stateRoot, schedule: s, slot, now = () => new Date(clock.currentTimeMillisUnsafe()) } = opts;
         const firedAt = now();
         const skippedReason = yield* Effect.try({
             try: () => {
@@ -154,9 +155,29 @@ export function fireRoutineOnce(opts) {
         });
         if (skippedReason !== undefined)
             return { fired: false, skippedReason, ms: 0 };
-        const r = yield* runTurn(agent, s.name, routineSession(s.name), s.prompt);
+        // Before anything is sent: the session it continues (created and recorded the first time), and its prompt.
+        const prepared = yield* Effect.tryPromise({
+            try: async () => ({
+                sessionId: await scheduleSessions(stateRoot).of(s.name, agent),
+                text: typeof s.prompt === "string" ? s.prompt : await s.prompt({ at: slot }),
+            }),
+            catch: (cause) => new PortFailure(cause),
+        }).pipe(Effect.result);
+        if (Result.isFailure(prepared)) {
+            const failed = `could not prepare the fire: ${String(prepared.failure.cause)}`;
+            log.error(`[schedule] ${s.name} failed${oneLine(failed)}`);
+            settleClaim(stateRoot, s.name, slot, "failed", 0);
+            return { fired: true, failed, ms: 0 };
+        }
+        // An occurrence on a busy session is refused, and so skipped; its key is the instant, so one occurrence is one run.
+        const r = yield* runTurn(agent, s.name, {
+            sessionId: prepared.success.sessionId,
+            content: [{ type: "text", text: prepared.success.text }],
+            whenBusy: "reject",
+            idempotencyKey: slot.toISOString(),
+        });
         // 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
+        // what decided it was the previous turn still holding the schedule's session, 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);
@@ -167,10 +188,89 @@ export function fireRoutineOnce(opts) {
                 ms: r.ms,
             };
         }
-        settleClaim(stateRoot, s.name, slot, r.failed ? "failed" : "completed", r.ms);
-        return { fired: true, failed: r.failed, ms: r.ms };
+        settleClaim(stateRoot, s.name, slot, r.fire, r.ms);
+        return { fired: true, ...(r.failed === undefined ? {} : { failed: r.failed }), ms: r.ms };
     }).pipe(Effect.uninterruptible);
 }
+/**
+ * Fire `schedule` once, now, outside its clock (`fastagent schedules run`), the way its clock would: a newest claim no
+ * fire reported is accounted for first, as a boot does, then this instant is the slot, claimed and settled as any.
+ */
+export function fireScheduleNow(opts) {
+    return Effect.gen(function* () {
+        const { agent, stateRoot, schedule } = opts;
+        const fire = yield* Effect.try({
+            try: () => latestFire(stateRoot, schedule.name),
+            catch: (cause) => new PortFailure(cause),
+        });
+        if (fire !== undefined && fire.outcome === undefined) {
+            yield* accountForUnreportedFire(agent, stateRoot, schedule.name, fire);
+        }
+        const slot = new Date((yield* Clock.Clock).currentTimeMillisUnsafe());
+        return { slot, ...(yield* fireScheduleOnce({ agent, stateRoot, schedule, slot })) };
+    });
+}
+/**
+ * Account for a claim whose fire never reported: the slot is claimed BEFORE its message is sent, and shutdown does not
+ * wait for the message (see `AgentService.close`), so a restart landing mid-fire leaves a claim nothing settled — the
+ * exact silence the history exists to prevent. Read once, at the next boot. The claim is the ONE record here: it IS
+ * the decision, and the outcome is written back into it.
+ *
+ * WHAT BECAME OF ITS MESSAGE decides the outcome. One the agent took is durable: it is answered after the restart
+ * (or already was), so its end is read through its key and written back, as the fire that ran would have. One that was
+ * never taken is `interrupted`, and NOT re-fired: a fire that kills its own process would then replay on every boot.
+ * Cron only: a killed wake-up leaves no claim behind (`takeFirstDueWakeup` removes it before its message is sent).
+ *
+ * THE NEWEST CLAIM ONLY. A schedule's loop runs one fire 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.
+ */
+function accountForUnreportedFire(agent, stateRoot, name, fire) {
+    return Effect.gen(function* () {
+        // `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.
+        const slot = new Date(fire.slot);
+        const key = slot.toISOString();
+        const sessionId = scheduleSessions(stateRoot).get(name);
+        const taken = sessionId === undefined
+            ? undefined
+            : yield* Effect.tryPromise({
+                try: () => agent.messages.get({ sessionId, idempotencyKey: key }).catch((error) => {
+                    if (error instanceof AgentError && error.code === "not_found")
+                        return undefined;
+                    throw error;
+                }),
+                catch: (cause) => new PortFailure(cause),
+            });
+        if (sessionId === undefined || taken === undefined) {
+            log.warn(`[schedule] ${name}: the fire claimed at ${fire.firedAt} never sent its message — the process stopped ` +
+                `before it, and that slot stays skipped (see \`fastagent schedules list\`)`);
+            // No duration: this fire was never timed, and the process that could have timed it is gone.
+            settleClaim(stateRoot, name, slot, "interrupted");
+            return;
+        }
+        log.info(`[schedule] ${name}: the fire claimed at ${fire.firedAt} was taken before a restart — reading its end`);
+        const end = yield* Effect.tryPromise({
+            try: (signal) => untilEnded(agent, { sessionId, idempotencyKey: key }, signal),
+            catch: (cause) => new PortFailure(cause),
+        });
+        if (!("ended" in end)) {
+            // Unsettled still, so the next boot reads it again.
+            log.warn(`[schedule] ${name}: the end of the fire claimed at ${fire.firedAt} is not known yet${oneLine("refused" in end ? end.refused : end.unfinished)}`);
+            return;
+        }
+        const { fire: outcome, detail } = settled(end.ended);
+        if (outcome === "completed")
+            log.info(`[schedule] ${name}: the fire claimed at ${fire.firedAt} completed`);
+        else
+            log.error(`[schedule] ${name}: the fire claimed at ${fire.firedAt} ${outcome}${oneLine(detail ?? "")}`);
+        // No duration either: only its end was seen here.
+        settleClaim(stateRoot, name, slot, outcome);
+    });
+}
+/** Which session each schedule continues: one per schedule, so the agent sees what its earlier runs did. */
+export function scheduleSessions(stateRoot) {
+    return conversationSessions(join(stateRoot, "schedule", "sessions.json"));
+}
 /** Wakes re-enter a chat session; identify the agent's own instruction and its cancellation handle. */
 function wakeEnvelope(w) {
     const tag = w.cron
@@ -182,21 +282,19 @@ 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 { agent, stateRoot, schedules, localClock = true, now = () => new Date(clock.currentTimeMillisUnsafe()), } = 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 launch = (label, work) => fork(Effect.withFiber((fiber) => {
+            // Publish ownership before a synchronous agent 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) {
@@ -209,14 +307,19 @@ export function createScheduler(options) {
                 }
                 // `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(() => {
+                yield* fireScheduleOnce({ agent, stateRoot, schedule: 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());
+                due = nextRun(s.cron, s.tz, now());
             }
         });
+        /**
+         * Fire the first due wake-up into its session, queued behind whatever runs there. The wake-up is taken out of the
+         * store first, so accepted is delivered: the pump goes on to the next one, and how the message ends is followed
+         * apart.
+         */
         const wakeOnce = Effect.gen(function* () {
             const w = yield* Effect.try({
                 try: () => takeFirstDueWakeup(stateRoot, now()),
@@ -224,27 +327,31 @@ export function createScheduler(options) {
             });
             if (!w)
                 return false;
+            const label = `wake ${w.id.slice(0, 8)}`;
+            const request = {
+                sessionId: w.session,
+                content: [{ type: "text", text: wakeEnvelope(w) }],
+                whenBusy: "queue",
+                idempotencyKey: `wake:${w.id}@${w.fireAt}`,
+            };
+            // Counted until the message is accepted: from then on the message itself is the work in flight.
             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)),
+                const accepted = yield* Deferred.make();
+                const delivered = () => void Deferred.doneUnsafe(accepted, Effect.void);
+                const followed = runTurn(agent, label, request, delivered).pipe(Effect.tap((r) => 
+                // Queued, it is refused only while the process or its session's queue is full: for now. A recurring
+                // wake-up has its next occurrence; a one-shot one goes back in the store, for the next poll.
+                r.busy && w.cron === undefined
+                    ? Effect.try({
+                        try: () => {
+                            requeueWakeup(stateRoot, w, new Date(now().getTime() + WAKEUP_POLL_MS));
+                            log.info(`[schedule] ${label}: refused for now — retrying next poll (${r.failed})`);
+                        },
                         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`);
-                }
-                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`);
-                }
-                // 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.
+                    }).pipe(Effect.catchTag("PortFailure", (error) => Effect.sync(() => log.error(`[schedule] ${label}: refused, and could not be kept for a retry, so it is gone: ${String(error.cause)}`))))
+                    : Effect.void), Effect.ensuring(Effect.sync(delivered)));
+                launch(label, Effect.asVoid(followed));
+                yield* Deferred.await(accepted);
             }), (done) => Effect.sync(done));
             return true;
         }).pipe(
@@ -261,6 +368,16 @@ export function createScheduler(options) {
                 yield* Effect.sleep(WAKEUP_POLL_MS);
             }
         });
+        /** Arm `s` to fire next at `due`, or say it never will. */
+        const arm = (s, due) => {
+            if (!localClock)
+                return;
+            if (!due) {
+                log.warn(`[schedule] ${s.name}: cron "${s.cron}" will never fire again — not armed`);
+                return;
+            }
+            launch(s.name, cronLoop(s, due));
+        };
         return {
             start() {
                 stopped = false;
@@ -270,34 +387,31 @@ export function createScheduler(options) {
                 // 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);
-                    }
+                for (const s of schedules) {
+                    const fire = latestFire(stateRoot, s.name);
+                    if (fire === undefined)
+                        continue;
+                    lastFires.set(s.name, fire.firedAt);
+                    if (fire.outcome !== undefined)
+                        continue;
+                    const accounted = accountForUnreportedFire(agent, stateRoot, s.name, fire).pipe(Effect.catchTag("PortFailure", (error) => Effect.sync(() => 
+                    // Unsettled still, so the next boot reads it again.
+                    log.error(`[schedule] ${s.name}: could not account for the fire claimed at ${fire.firedAt}: ${String(error.cause)}`))));
+                    launch(s.name, accounted);
                 }
                 const current = now();
-                for (const s of externalClock ? [] : routines) {
+                for (const s of schedules) {
                     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
+                    // FROM THE LAST FIRE, or from now when there was none. A schedule 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())
+                    if (localClock && due && due.getTime() <= current.getTime()) {
                         log.info(`[schedule] ${s.name}: catching up a missed run`);
-                    launch(s.name, cronLoop(s, due));
+                    }
+                    arm(s, due);
                 }
                 if (!stopped)
                     launch("wake-up poll", wakeLoop);

package/dist/schedule/state.d.ts

@@ -10,7 +10,7 @@ export declare function writeScheduleFile(path: string, value: unknown): void;
  * How a claimed occurrence ended.
  *
  * `skipped` is NOT a failure and is the reason this is an enum rather than a boolean: a schedule's turns share one
- * `routine:<name>` session, so an occurrence arriving while the previous one is still running is refused by that
+ * `schedule:<name>` session, so an occurrence arriving while the previous one is still running is refused by that
  * session, and recording it as `failed` made "the last run was still going" indistinguishable from "the model call
  * died" — two things an operator reacts to completely differently. Every scheduler names this: Kubernetes calls it
  * `concurrencyPolicy: Forbid`, Temporal calls it the `Skip` overlap policy, and neither treats it as an error.
@@ -25,16 +25,6 @@ export interface Fire {
     outcome?: FireOutcome;
     ms?: number;
 }
-/**
- * A schedule name becomes a path segment (its claims live in `claims/<name>/`), so the rule is exactly the safety
- * boundary and nothing more: a name may not leave that directory. The name comes from a filename under `routines/`,
- * which already cannot contain a separator — so what a stricter rule would actually reject is legal filenames
- * (`每日简报`, `my schedule`), whose only symptom would be a schedule that silently never fires again.
- *
- * One definition, two enforcers: `discover.ts` refuses an illegal one where the author can see which file is wrong,
- * and `claimDir` asserts it again for a programmatic caller.
- */
-export declare function isSafeScheduleName(name: string): boolean;
 /**
  * Why a slot is not ours. `duplicate` is ordinary (the same delivery arrived twice, or another scheduler took it and
  * is running it now); `stale` means the schedule has moved past this instant and the slot will never run — a turn
@@ -75,9 +65,9 @@ export declare function claimSlot(stateRoot: string, name: string, slot: Date, f
  * the history. Nothing here grows: the pruning that keeps the claim gate cheap keeps the history's size fixed too,
  * which is why there is no separate audit file to rotate (what the turn SAID is in its session, not here).
  *
- * THE HISTORY read, and its only caller is the read-only `routine history` — which translates a read fault into a
- * one-line refusal. The serving boot reads `latestFire` instead: it asks about ONE claim, and a window of files kept
- * for an operator to look at has no business deciding whether a service starts.
+ * THE HISTORY read, and its only caller is the read-only `schedules list --json` — which translates a read fault into a
+ * one-line refusal. Its text mode and the serving boot read `latestFire` instead: each asks about ONE claim, and a
+ * window of files kept for an operator to look at has no business failing either.
  */
 export declare function readFires(stateRoot: string, name: string): Fire[];
 /**

package/dist/schedule/state.js

@@ -32,8 +32,8 @@ export function writeScheduleFile(path, value) {
 }
 // ── claims/: one file per fired slot — the DECISION to fire, made atomically ──
 /**
- * How many claims to keep per schedule — and therefore how far back `fastagent routine history` can see, since
- * the claims ARE the history. The gate below reads only the newest, so this number answers the history's question,
+ * How many claims to keep per schedule — and therefore how far back the fire history under
+ * `<stateRoot>/schedule/claims/<name>/` reaches, since the claims ARE the history. The gate below reads only the newest, so this number answers the history's question,
  * "did last night's run silently fail?": at 512 a minute cron keeps ~8.5 hours, an hourly one ~3 weeks.
  *
  * Raise it by FILE COUNT, not by byte count: 512 short lines are ~25 KB of content but ~2 MiB of blocks and 512
@@ -151,14 +151,14 @@ function readClaim(dir, name) {
 }
 /**
  * A schedule name becomes a path segment (its claims live in `claims/<name>/`), so the rule is exactly the safety
- * boundary and nothing more: a name may not leave that directory. The name comes from a filename under `routines/`,
+ * boundary and nothing more: a name may not leave that directory. The name comes from a filename under `schedules/`,
  * which already cannot contain a separator — so what a stricter rule would actually reject is legal filenames
  * (`每日简报`, `my schedule`), whose only symptom would be a schedule that silently never fires again.
  *
  * One definition, two enforcers: `discover.ts` refuses an illegal one where the author can see which file is wrong,
  * and `claimDir` asserts it again for a programmatic caller.
  */
-export function isSafeScheduleName(name) {
+function isSafeScheduleName(name) {
     return name !== "" && !/[/\\]/.test(name) && !name.includes("\u0000") && name !== "." && name !== "..";
 }
 /** This function builds a path from it, so a name that can leave `claims/<name>/` is a bug, not an input. */
@@ -226,9 +226,9 @@ export function claimSlot(stateRoot, name, slot, firedAt) {
  * the history. Nothing here grows: the pruning that keeps the claim gate cheap keeps the history's size fixed too,
  * which is why there is no separate audit file to rotate (what the turn SAID is in its session, not here).
  *
- * THE HISTORY read, and its only caller is the read-only `routine history` — which translates a read fault into a
- * one-line refusal. The serving boot reads `latestFire` instead: it asks about ONE claim, and a window of files kept
- * for an operator to look at has no business deciding whether a service starts.
+ * THE HISTORY read, and its only caller is the read-only `schedules list --json` — which translates a read fault into a
+ * one-line refusal. Its text mode and the serving boot read `latestFire` instead: each asks about ONE claim, and a
+ * window of files kept for an operator to look at has no business failing either.
  */
 export function readFires(stateRoot, name) {
     const dir = claimDir(stateRoot, name);

package/dist/schedule/wake-alarm.d.ts

@@ -1,6 +1,7 @@
 import * as Effect from "effect/Effect";
-import { type WakeAlarm } from "../channels/agentcore-protocol.ts";
+import { type RecurringSchedule, type WakeAlarm } from "../channels/agentcore-protocol.ts";
 import { type Wakeup } from "./wakeups.ts";
+import type { Schedule } from "./schedule.ts";
 /**
  * Persist the forwarder URL the adapter saw in an envelope (write-if-changed — envelopes arrive on every turn, the
  * file should not churn).
@@ -13,14 +14,33 @@ export declare function readWakeAlarmUrl(stateRoot: string): string | undefined;
  * the pending store is the durable desired state — so "give up" means "until the next mirror", never "lost").
  */
 export declare const MAX_SYNC_ATTEMPTS = 5;
-/** Pending wake-ups → the desired alarm set, minus already-due entries (see {@link DUE_MARGIN_MS}). */
+/**
+ * After a whole sync gives up, how long until it is tried again, for as long as this process lives. Outside the busy
+ * count, so a container that is only waiting to retry can still be reclaimed; its next start mirrors again.
+ */
+export declare const HEAL_MS: number;
+/**
+ * Pending wake-ups → the desired one-shot alarms. A wake-up already due is left out (see {@link DUE_MARGIN_MS}): the
+ * container is awake for it, and its wake pump fires it.
+ *
+ * ONE ID PER INSTANT, never per wake-up. An alarm deletes itself once it has fired, and a recurring wake-up's claim
+ * mirrors its next instant right after: an id reused for it would update the alarm EventBridge is about to delete,
+ * and the next instant would be deleted with it. With one id per instant, mirroring again is idempotent.
+ */
 export declare function toAlarms(pending: Wakeup[], now: Date): WakeAlarm[];
+/**
+ * Each armed schedule → the recurring EventBridge schedule that fires it. Discovery admits only a cron that
+ * translates (schedule/discover.ts), so one that does not here is a defect, and throws.
+ */
+export declare function toRecurring(schedules: readonly Schedule[]): RecurringSchedule[];
 /**
  * Build the wakeups sink for an AgentCore deployment (registered via `setWakeupsSink` by `start` when
  * `FASTAGENT_AGENTCORE=1` + `FASTAGENT_WAKE_SECRET` are present).
  */
 export declare function createWakeAlarmSink(options: {
     secret: string;
+    /** The schedules armed now, mirrored as recurring schedules beside the wake-ups' alarms. */
+    schedules?: () => readonly Schedule[];
     fetchImpl?: typeof fetch;
     /** Injectable clock (tests); defaults to the wall clock. */
     now?: () => Date;