hir-94: actually reschedule queue entries when an account is over quota

[jaredzwick]

Summary

The quota-exceeded branch in processEmailQueue claimed to "reschedule for quota reset time" but the underlying updateQueueStatus call only touched status and errorMessage — scheduledFor stayed at its original value. Since getNextPendingEmails filters by scheduledFor <= now, the same entry got re-picked on every batch, re-checked unsubscribe + quota, and re-skipped. Under sustained load with one over-quota account, the processor's entire batch fills with the same N entries every iteration and other accounts' work starves.

Changes

• libs/db/src/queries/emailQueue.ts: new rescheduleQueueEntry(id, newScheduledFor, errorMessage?) helper. Keeps status pending, bumps scheduledFor, sets updatedAt. Does NOT increment attemptCount because no send was attempted.
• src/lib/queueScheduling.ts (new): pure computeQuotaRescheduleAt(quotaResetAt, now?, minDelayMs?). Honors the account's stored quota reset when it's far enough out; floors at now + minDelay (default 1 minute) when the reset is null, in the past, equal to now, or sooner than the floor. Always returns a Date >= now so we never schedule backwards.
• src/lib/emailQueueProcessor.ts: quota-exceeded branch calls rescheduleQueueEntry with the computed Date. Also drops the previous "reset is in the past → fall through and try to send" path. A fresh quota window is the account row's responsibility; falling through would attempt a send against an account whose quotaUsedToday is still at the limit. Safer to wait for the reset to be applied.

Tests

• tests/int/queueScheduling.int.spec.ts — 12 specs: future reset honored; null/undefined fallback; past-reset floor; equal-to-now floor; sub-floor reset clamped to floor; just-past-floor reset honored; custom minDelayMs; negative minDelayMs clamped to zero; fresh-Date guarantee (output is not the input reference); default-now omission; "output >= now" property across a parametric input set.
• All 12 new tests pass. Full pnpm test:int: 107/108 pass; the 1 failure is the pre-existing api.int.spec.ts Payload-secret issue on main, unrelated.
• pnpm lint clean for all changed files.

Regression analysis

• The processor's other branches (sent, failed, retry, max-attempts, unsubscribed, scheduled-in-future) are untouched.
• updateQueueStatus is still used everywhere it was before. The new rescheduleQueueEntry is additive.
• Removing the "reset already in the past → try to send anyway" fall-through is a behavior change, but the previous behavior was buggy: it would attempt a Gmail send against an account whose quotaUsedToday had not been reset, which Gmail would reject and the entry would then count as a real failure (incrementing attemptCount toward the max-attempts cap). The new behavior — wait for the reset — is strictly safer.

Test plan

• Manually exhaust a connected Gmail account's daily quota (set dailyQuota: 1 and quotaUsedToday: 1 in the DB).
• Create a campaign with 10 recipients on that account, plus 5 recipients on a second connected account.
• POST /api/email-queue/process and confirm: the 5 entries on account feat: email template library + /templates page + Browse picker (HIR-75) #2 send; the 10 entries on the over-quota account get scheduledFor bumped to the account's quotaResetAt, and the next process call no longer re-picks them.
• Manually set quotaUsedToday: 0 and quotaResetAt: now() + 1 hour, set the queue entry's scheduledFor: now() + 30 seconds, and confirm a process call right now does not re-pick it.

Cumulative HIR-94 progress

• ✅ #8 — Gmail OAuth connect (22 specs)
• ✅ #9 — Campaign create UI + recipient parser (9 specs)
• ✅ #10 — RFC-correct MIME (41 specs)
• 🟡 #13 — Per-recipient variables + substitution (25 new specs)
• 🟡 This PR — Queue quota-rescheduling (12 specs)
• ⏭ Next: CSV recipient upload; daily quota reset job.

🤖 Generated with Claude Code

[jaredzwick]

CTO Review — PR #18 (hir-94: quota reschedule fix)

Verdict: LGTM — this is a real bug fix

The bug: processEmailQueue quota-exceeded path updated status and errorMessage but left scheduledFor unchanged. Since getNextPendingEmails filters scheduledFor <= now, the same entry was re-picked every batch, re-checked, and re-skipped in a tight loop. This silently burns quota-check cycles and blocks the queue.

The fix correctly sets scheduledFor to the quota reset time, so the entry won't re-surface until the account's quota window clears. Ready to merge.

[jaredzwick]

CTO Review — LGTM

Core fix is correct and well-scoped.

Bug fixed: Old path called updateQueueStatus(id, 'pending', null, 'Quota exceeded') which kept status pending but never bumped scheduledFor. Since getNextPendingEmails filters scheduledFor <= now, the entry was re-picked on every batch iteration and spun forever. New path calls rescheduleQueueEntry which actually advances scheduledFor.

rescheduleQueueEntry (db layer): Clean separation from the existing updateQueueStatus. Correctly does NOT touch attemptCount — no send was attempted, only a scheduling decision was made. The conditional errorMessage update pattern avoids clobbering an existing message with null unless the caller explicitly passes undefined — good.

computeQuotaRescheduleAt (pure function): Logic is correct. Floor of now + minDelayMs prevents a tight loop when quotaResetAt is null, past, or too close. Math.max(minDelayMs, 0) handles the negative-delay edge case. Returns a fresh Date instance — safe for callers that mutate.

Test suite: 11 cases, covers all boundary conditions. Particularly good: the invariant test at the end that asserts output >= now for every possible input class.

No concerns. Ready to merge after PR #13, #20, #22 land (same base, no conflicts expected — these are independent feature slices).