Cron dispatcher: a late tick catches up the firings it missed (JOB-001)

[NewWorldVenture]

Why

scripts/cron-dispatch.mjs is what gives the app its sub-daily cron cadence on Vercel Hobby: .github/workflows/cron-dispatch.yml asks GitHub to run it every five minutes, and it calls every /api/cron/* route whose schedule fell due. It evaluated a fixed five-minute window ending at the moment it ran, and GitHub starts scheduled workflows hours late (measured gaps of 104–396 minutes, median 209), so every sub-daily firing between two ticks was simply lost. tests/a-late-tick-drops-a-cron.test.ts characterized that; nothing fixed it. Ledger row JOB-001 (🔄 IN PROGRESS, High) names this as the remaining scheduler scope in docs/final-audit/cron-dispatch-cycle.md. finalaudit.md is untouched; this is the repository-side fix with its evidence.

What changes

scripts/cron-dispatch.mjs

• tickWindow(now, since): the window is (since, now], never narrower than the fixed five minutes (two quick runs cannot lose the minutes between them) and clamped at CATCH_UP_MAX_MINUTES = 24 h. Clamped rather than ignored, because the gaps this exists for are the long ones: a weeks-old boundary after the workflow was disabled still recovers one call per sub-daily route. A missing, unparseable or future CRON_SINCE keeps the fixed window and says why in the log line.
• dueRoutes(…, since): each route is called at most once per tick however many of its minutes fell in the window; the routes are sweeps, not slot replays.
• isSubDaily: only routes that fire more than once a day are caught up. The once-a-day ones are exactly what Vercel Hobby accepts and vercel.json mirrors at the same minute, so Vercel already fired them; catching one up would be a second daily run (a second admin-digest email). Inside the fixed window they are evaluated exactly as before.
• Why 24 h: model-refresh (0 4,16) and autopilot-scan (30 6,18) have 12-hour periods, and every caught-up route has a due minute in any 24 h window, so a wider cap cannot add a route. A test checks the cap against the longest gap in the table, so a slower route cannot be added silently.
• SCHEDULES is byte-identical; --dry-run stays credential-free; --route ignores the boundary; every existing validation (secret presence, base-URL rules, redirect refusal, bounded responses, deadline, redaction) is unchanged.

.github/workflows/cron-dispatch.yml

• A step before dispatch asks the Actions API (actions: read, the job's own token) for the previous successful scheduled run of this workflow, excluding the current run, validates the timestamp shape and passes it as CRON_SINCE. Manual single-route runs are not a boundary (they would collapse the next window). A failed lookup logs and falls back to the five-minute window; it never fails the tick. The cron string, sparse checkout, concurrency and repository guard are unchanged.

Tests

• tests/a-late-tick-drops-a-cron.test.ts → tests/a-late-tick-catches-up.test.ts (git mv; 7 cases; the late tick is now caught up; the measurement paragraph and the corrected severity model are kept).
• tests/cron-dispatch.test.ts +12: window, cap, clamp, once-per-route, the daily exclusion equals the vercel.json mirror set, the cap against the table's longest gap; "vercel.json ↔ dispatcher table" untouched.
• tests/cron-dispatch-execution.test.ts +6 CLI cases: catch-up, clamp, fallbacks for bad input, dry run with a boundary, --route ignoring it.
• Comment-only pointer updates in two tests and one README for the renamed file.

Docs: docs/final-audit/cron-dispatch-cycle.md gains a dated section on the design and its evidence (additive).

Evidence (local; nothing touched GitHub Actions or production)

• 16 related files, 255 tests pass (the cron suites, the admin-digest files that pin dispatcher lines, a-mirrored-cron-must-be-idempotent, a-paths-filter-must-list-what-it-gates, production-readiness-workflow, test-harness-config-is-what-it-says, health-feature-secrets, cron-auth). ESLint clean; node --check ok; the workflow parses (PyYAML and js-yaml); git diff --check clean.
• Dry runs: without CRON_SINCE, the log line is byte-identical to before; with a 187-minute boundary the twelve sub-daily routes due in the gap are listed once each and the daily notifications is not; not-a-date and a future timestamp fall back and say why; a 2-minute-old boundary stays at the five-minute window; a boundary older than the cap is clamped and lists all 17 sub-daily routes and no daily one; --route ignores the boundary.
• The previous-tick step was run under bash -eo pipefail with a fake gh: success writes the boundary; a 403, an empty body, null and a missing gh all log the fallback and exit 0.
• Mutation controls, each on the script alone: dropping once-per-route fails 4 tests; dropping the cap fails 3; dropping the future check fails 2; dropping the daily exclusion fails 4.

What this does not change

• The delivered rate: a */5 route still runs once per tick however many of its minutes the tick covered (a-cron-cadence-is-a-promise-nothing-keeps is unchanged). Recovering the rate needs a scheduler that keeps its word, as the workflow's own note says.
• The known same-minute admin-digest double send between vercel.json and the dispatcher.
• No schedule, secret, trigger or production setting; the workflow change takes effect only when merged.

🤖 Generated with Claude Code

https://claude.ai/code/session_01KP9rt5rVQ9jDMpZp2xBy3K

---

Generated by Claude Code

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

1 Skipped Deployment

Project	Deployment	Actions	Updated
bubaly	Ignored		Oct 3, 2026 12:26pm UTC