Replace Polling Loop with Agenda.js Job Scheduler for Shift Monitoring

[Dharp02]

Overview

Replaces the old ClockMonitorService polling loop (a setInterval that scanned all active clock events every 30 seconds) with Agenda.js — a MongoDB-backed job scheduler. This eliminates unnecessary database scans and ties each job precisely to the clock-in event that triggered it.

How Agenda.js Works

Agenda stores scheduled jobs in MongoDB (the agendajobs collection). Each job has a name, a nextRunAt timestamp, and a payload. When a job's scheduled time arrives, Agenda processes it and executes the registered handler. Key configuration:

• processEvery: "30 seconds" — Agenda polls MongoDB every 30s to pick up due jobs.
• defaultLockLifetime: 10_000 — Jobs are locked for up to 10s to prevent double-processing across server restarts.

Three Jobs Scheduled per Clock-In

Job	Fires at	Action
shift-4h-reminder	startTime + 4h	Creates a push notification (break reminder)
shift-end-reminder	startTime + 7h 45m	Broadcasts SSE message → opens modal on frontend
shift-auto-clockout	startTime + 8h	Auto-clocks out the user only if they clicked "Agree to Clock Out"

All three jobs are scheduled atomically when the user clocks in (scheduleClockJobs()) and cancelled atomically when the user clocks out (cancelClockJobs()).

What Changed

Backend

• Added backend/src/services/agenda.service.ts — Agenda instance, job definitions, initAgenda()/stopAgenda()/scheduleClockJobs()/cancelClockJobs() helpers.
• Deleted backend/src/services/clock-monitor.service.ts — the old setInterval-based polling service. Replaced entirely by Agenda.
• clock.service.ts — clockIn() now calls scheduleClockJobs(); clockOut() calls cancelClockJobs(). Added agreeAutoClockout() to mark a session as consented to auto-clockout.
• New route + controller — POST /v1/clock/:id/agree-clockout for the frontend modal "Agree to Clock Out" button.
• server.ts — Calls initAgenda() on startup (skipped in test env) and stopAgenda() on graceful shutdown.
• backend/package.json — Added agenda and @agendajs/mongo-backend.

Frontend

• Added src/features/notifications/ShiftReminderContext.tsx — Listens on the SSE stream for shift-end-reminder messages, opens a modal asking "Continue Working" or "Agree to Clock Out", and calls the new agree endpoint.
• src/ui/AppLayout.tsx — Wraps the app in ShiftReminderContext.
• src/lib/api.ts — Added agreeAutoClockout(clockEventId) API helper.

E2E Tests

• Added e2e/shift-reminder.spec.ts — Full coverage of the shift-end reminder flow: modal appears after 7h 45m, "Agree" sets the flag, "Continue Working" dismisses without flagging.
• Fixed e2e/clock-breaks.spec.ts, e2e/work.spec.ts, e2e/pulsevault.spec.ts, e2e/tickets.spec.ts — Added explicit Authorization: Bearer headers for page.request API calls (better-auth uses localStorage tokens, not cookies, so page.request had no auth).

Acceptance Criteria

• Clock-in schedules all three Agenda jobs in MongoDB
• Clock-out cancels all three jobs
• 4h push notification fires via notificationService.create()
• 7h 45m SSE broadcast opens modal on frontend
• "Agree to Clock Out" sets autoClockoutAgreed=true and triggers auto-clockout at 8h
• "Continue Working" dismisses modal with no side effects
• clock-monitor.service.ts removed — no polling loops remain
• All 33 E2E tests pass
• All 287 backend unit tests pass