feat(finalist): admin alerts on confirm/decline/expire/promote

Wire notifyAdmins() into finalist lifecycle events so admins receive
in-app (+ email when enabled) notifications on each key transition:
- finalist.confirm → FINALIST_CONFIRMED
- finalist.decline / adminDecline → FINALIST_DECLINED
- expirePendingPastDeadline (per row) → FINALIST_EXPIRED
- promoteNextWaitlistEntry + manualPromote → FINALIST_WAITLIST_PROMOTED

All calls are wrapped in try/catch — comms never throw inside a mutation
or cron (CLAUDE.md: "round notifications never throw"). Added project
title to the project select where it was missing.

Tests: tests/unit/finalist-comms.test.ts — 3 tests passing (TDD).
Regression: finalist-confirmation, finalist-admin-confirm,
finalist-enrollment — 30 tests all passing.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

src/server/routers/finalist.ts

@@ -9,6 +9,7 @@ import {
 } from '../services/finalist-confirmation'
 import {
   createNotification,
+  notifyAdmins,
   NotificationTypes,
 } from '../services/in-app-notification'
 import { sendFinalistConfirmationEmail } from '@/lib/email'
@@ -298,6 +299,7 @@ export const finalistRouter = router({
           project: {
             select: {
               id: true,
+              title: true,
               programId: true,
               program: { select: { defaultAttendeeCap: true } },
               teamMembers: { select: { userId: true } },
@@ -374,6 +376,22 @@ export const finalistRouter = router({
           attendingUserIds: input.attendingUserIds,
         },
       })
+      // Admin alert — best-effort, never throws
+      try {
+        await notifyAdmins({
+          type: NotificationTypes.FINALIST_CONFIRMED,
+          title: 'Finalist confirmed',
+          message: `"${confirmation.project.title}" (${confirmation.category}) has confirmed grand-finale attendance.`,
+          linkUrl: '/admin/logistics',
+          metadata: {
+            projectId: confirmation.projectId,
+            projectTitle: confirmation.project.title,
+            category: confirmation.category,
+          },
+        })
+      } catch (err) {
+        console.error('[finalist.confirm] failed to send admin notification:', err)
+      }
       return { ok: true }
     }),
 
@@ -390,7 +408,7 @@ export const finalistRouter = router({
       const payload = verifyFinalistToken(input.token)
       const confirmation = await ctx.prisma.finalistConfirmation.findUnique({
         where: { id: payload.confirmationId },
-        include: { project: { select: { programId: true } } },
+        include: { project: { select: { programId: true, title: true } } },
       })
       if (!confirmation) throw new TRPCError({ code: 'NOT_FOUND' })
       if (confirmation.token !== input.token) {
@@ -420,6 +438,22 @@ export const finalistRouter = router({
           reason: input.reason ?? null,
         },
       })
+      // Admin alert — best-effort, never throws
+      try {
+        await notifyAdmins({
+          type: NotificationTypes.FINALIST_DECLINED,
+          title: 'Finalist declined',
+          message: `"${confirmation.project.title}" (${confirmation.category}) has declined grand-finale attendance.`,
+          linkUrl: '/admin/logistics',
+          metadata: {
+            projectId: confirmation.projectId,
+            projectTitle: confirmation.project.title,
+            category: confirmation.category,
+          },
+        })
+      } catch (err) {
+        console.error('[finalist.decline] failed to send admin notification:', err)
+      }
 
       // Promote next waitlist entry in same category. windowHours pulled from
       // the live grand-finale round in the program (LIVE_FINAL roundType).
@@ -525,7 +559,7 @@ export const finalistRouter = router({
     .mutation(async ({ ctx, input }) => {
       const confirmation = await ctx.prisma.finalistConfirmation.findUniqueOrThrow({
         where: { id: input.confirmationId },
-        include: { project: { select: { programId: true } } },
+        include: { project: { select: { programId: true, title: true } } },
       })
       if (confirmation.status !== 'PENDING') {
         throw new TRPCError({
@@ -552,6 +586,22 @@ export const finalistRouter = router({
           reason: input.reason ?? null,
         },
       })
+      // Admin alert — best-effort, never throws
+      try {
+        await notifyAdmins({
+          type: NotificationTypes.FINALIST_DECLINED,
+          title: 'Finalist declined (admin)',
+          message: `"${confirmation.project.title}" (${confirmation.category}) was declined by an admin.`,
+          linkUrl: '/admin/logistics',
+          metadata: {
+            projectId: confirmation.projectId,
+            projectTitle: confirmation.project.title,
+            category: confirmation.category,
+          },
+        })
+      } catch (err) {
+        console.error('[finalist.adminDecline] failed to send admin notification:', err)
+      }
 
       const round = await ctx.prisma.round.findFirst({
         where: {
@@ -908,6 +958,23 @@ export const finalistRouter = router({
           windowHours: input.windowHours,
         },
       })
+      // Admin alert — best-effort, never throws
+      try {
+        const projectTitle = project?.title ?? entry.projectId
+        await notifyAdmins({
+          type: NotificationTypes.FINALIST_WAITLIST_PROMOTED,
+          title: 'Waitlist entry promoted',
+          message: `"${projectTitle}" (${entry.category}) was manually promoted from the waitlist.`,
+          linkUrl: '/admin/logistics',
+          metadata: {
+            projectId: entry.projectId,
+            projectTitle,
+            category: entry.category,
+          },
+        })
+      } catch (err) {
+        console.error('[finalist.manualPromote] failed to send admin notification:', err)
+      }
       return { confirmationId }
     }),
 

src/server/services/finalist-confirmation.ts

@@ -2,6 +2,7 @@ import type { CompetitionCategory, PrismaClient } from '@prisma/client'
 import { signFinalistToken } from '@/lib/finalist-token'
 import { sendFinalistConfirmationEmail } from '@/lib/email'
 import { logAudit } from '@/server/utils/audit'
+import { notifyAdmins, NotificationTypes } from './in-app-notification'
 
 type AnyPrisma = Pick<PrismaClient, 'finalistConfirmation' | 'waitlistEntry' | 'project'>
 
@@ -104,6 +105,27 @@ export async function promoteNextWaitlistEntry(
     }
   }
 
+  // Admin alert — best-effort, never throws
+  try {
+    const projectTitle = project?.title ?? entry.projectId
+    await notifyAdmins({
+      type: NotificationTypes.FINALIST_WAITLIST_PROMOTED,
+      title: 'Waitlist entry promoted',
+      message: `"${projectTitle}" (${args.category}) was promoted from the waitlist.`,
+      linkUrl: '/admin/logistics',
+      metadata: {
+        projectId: entry.projectId,
+        projectTitle,
+        category: args.category,
+      },
+    })
+  } catch (err) {
+    console.error(
+      `[promoteNextWaitlistEntry] failed to send admin notification for project ${entry.projectId}:`,
+      err,
+    )
+  }
+
   return { promoted: true, entryId: entry.id, confirmationId }
 }
 
@@ -131,6 +153,31 @@ export async function expirePendingPastDeadline(
       entityId: c.id,
       detailsJson: { projectId: c.projectId, category: c.category },
     })
+    // Admin alert — best-effort, never throws
+    try {
+      // Resolve project title for a meaningful notification message
+      const proj = await prisma.project.findUnique({
+        where: { id: c.projectId },
+        select: { title: true },
+      })
+      const projectTitle = proj?.title ?? c.projectId
+      await notifyAdmins({
+        type: NotificationTypes.FINALIST_EXPIRED,
+        title: 'Finalist confirmation expired',
+        message: `"${projectTitle}" (${c.category}) did not confirm in time — confirmation expired.`,
+        linkUrl: '/admin/logistics',
+        metadata: {
+          projectId: c.projectId,
+          projectTitle,
+          category: c.category,
+        },
+      })
+    } catch (err) {
+      console.error(
+        `[expirePendingPastDeadline] failed to send admin notification for project ${c.projectId}:`,
+        err,
+      )
+    }
     // Resolve windowHours for this program's grand-finale round
     const round = await prisma.round.findFirst({
       where: {