Alert when a scheduled report sends no email
Summary
An hourly check that finds scheduled reports that sent no email, tells the team on Telegram, and (once switched on) tells the customer.
Why
Today a report can stop without anyone knowing:
- Plan blocks are silent.
GET /api/tasks?id=answers 402 when the plan no longer covers a task; the Trigger runner (tasks/src/recoup/fetchTask.ts) treats that as "no task" and exits. The customer never hears, at exactly the moment an upgrade prompt would land. - Runs can stall with no step timeout (recoupable/app#2022).
- Sends get rejected at
POST /api/emails(recoupable/app#1949).
One check after the fact catches all three without fixing each path first.
How it works
- Cron
17 * * * *→GET /api/internal/missed-report-check(CRON_SECRET, same as the other internal crons). - Checks the clock hour that began three hours ago (at least two hours of grace for long reports). Windows are whole clock hours, so each run lands in exactly one, whatever second the cron fires.
- Each run is read once more to get its task id (the list endpoint omits schedule details).
- For tasks whose prompt asks for an email: was there a
sentrow inemail_send_logfor the task's account after the run started? The run's sandbox key is minted for the task's account (handleStartChatRun.ts:53), so its sends are logged there. This read throws on a database error, so "unknown" is never mistaken for "not sent". - A miss is classified as plan blocked (only when the run attempted no send, since the plan is read at check time), email rejected (with the reason from #1235), or no email (with the run status, which shows stalls).
- One Telegram message per hour lists the misses with account and run ids. A run that can't be checked is counted in the alert and skipped, so the rest of the batch still runs.
Customer emails are off until switched on
MISSED_REPORT_CUSTOMER_NOTICES=true turns on owner emails:
- Plan blocked: for any task, at most once per task every 30 days (a blocked task fires on every scheduled run). Says which task didn't run, the plan's limit, and the upgrade link. The notice is logged without an account, so it never counts as that account's report being sent.
- Other failures: only for the catalog report tasks onboarding and the homepage card create (they always email). Other tasks may email only sometimes, so they get the team alert only.
Every notice carries a per-run Resend idempotency key, so a duplicated cron delivery can't email twice (it can repeat the team alert). I couldn't read production to size the volume, so the team alert runs alone first. Turning notices on is one environment variable.
Known limits
- Matching is per account: two of an account's email tasks firing in the same window can mask each other.
- Up to 100 runs per hourly window are checked (a warning is logged at 100).
- If Vercel skips a cron delivery, that hour goes unchecked.
Merge order
This branch is built on #1235 (rejection reasons) and needs recoupable/database#132. Merge database#132, then #1235, then this. The diff shows #1235's commit until it merges.
Tests
Tests first: 6 new test files (window bounds, run listing, miss classification, notice rules, dedupe and escaping, alert text, handler flow including a failing run). An independent review's findings are addressed in a49a3730. pnpm vitest run → 9,303 passed. The 3 MCP test files that fail need a generated ./generated-ui module that a fresh worktree lacks; they fail the same way on main. ESLint and Prettier clean on changed files.
🤖 Generated with Claude Code