fix(cron): grace window must defer a fire, not drop it

[nyem69]

The bug

The catch-up sweep skipped any fire inside the 90 s grace window on the reasoning that "node-cron has not yet had its chance." On a post-sleep wake that reasoning is backwards: node-cron's minute-tick was suspended through that minute and never replays it — which is the entire reason this module exists.

The sweep then wrote writeCheckpoint(now) unconditionally in its finally, pushing lastCheck past the skipped fire. The next sweep rejected it via prevFire <= lastCheck. The fire was gone.

Net: a 90-second-wide blind spot immediately before every wake sweep. Recurring jobs hide it (they just fire again next interval); a date-pinned one-shot loses its fire until the schedule next comes round.

Observed in production

manamurah-ayam-hub-verdict-ONESHOT (30 9 14 7 *, Asia/Kuala_Lumpur) was due 2026-07-14T01:30:00Z. The host woke and swept at 01:30:59Z — 59 s < 90 s grace — so it was skipped, then buried. Jobs on either side of it replayed normally:

01:00  manamurah-kv-snapshot      replayed
01:22  collect-tiktok-selangor    replayed
01:30  ayam-hub-verdict           <-- silently dropped
01:40  plan-url-queue-processor   replayed

Its next natural fire would have been July 2027. Found because the one-shot was a deliberate re-check that never happened.

The fix

computeMissedFires now returns deferred: DeferredFire[] alongside replay/tooOld, and checkpointFloor(now, deferred) clamps the persisted checkpoint to min(now, earliestDeferred - 1).

The fire is reconsidered on the next sweep, by which point the grace has passed and the run-log dedup makes the real decision:

• node-cron fired it on time → dedup vetoes → no replay. This is the guard that fixed the 2026-06-07 sitrep double-fire, and it is unchanged.
• the host slept through it → no run-log entry → replayed once.

The grace window keeps its anti-race role but can no longer destroy a fire. Every skip path in this module is now replayed, deferred, or warned — none silent.

Tests

catchup.test.ts drives two consecutive sweeps and pins both failure modes:

• holds the checkpoint behind the deferred fire instead of advancing to now
• replays the fire on the next sweep when the host slept through it ← the drop
• does NOT replay when node-cron fired it on time (no double-fire) ← the June regression
• checkpointFloor — earliest-wins, never advances past now

Verified against the real production values (actual schedule + the actual 01:30:59Z wake from gateway.log): the old checkpoint buries the fire on both sweeps; the new one replays it. 798/798 tests pass, tsc --noEmit clean. Built and running on the live gateway (boot 54cfa5d3).

🤖 Generated with Claude Code

https://claude.ai/code/session_01B849gvnP1gpazo2U4R9hPN