Crash reports: per-row email, short ID, build mode

- New columns on `crash_reports` (D1): `build_mode` (`'release'` / `'debug'`, nullable) and `short_id` (`CRASH-XXXXX`, nullable + indexed). Both nullable so existing rows stay untouched. Two new migrations: `0003_crash_build_mode.sql`, `0004_crash_short_id.sql`.
- Desktop crash file now carries `buildMode` and `shortId`. The short id is generated at write time via the shared `short_id` module and surfaced in the next-launch dialog so the user has something to reference when they reach out.
- `POST /crash-report` accepts and validates both optional fields, persisting them through to D1.
- Cron crash-notification email rewritten: one row per crash report instead of grouping by `top_function`. Columns: When, Env, ID, Site, Signal, Version, sorted newest-first. `'?'` for old rows that don't have `buildMode`/`shortId`. Renamed `CrashSummaryEntry` → `CrashEmailRow`.
- Bindings regenerated. Tests updated to cover the new fields and the per-row email layout.
- `crash_reporter` and api-server `CLAUDE.md` docs updated.

Author: vdavid

apps/api-server/migrations/0003_crash_build_mode.sql

@@ -0,0 +1,3 @@
+-- Distinguish dev-build crashes from production crashes in the email summary.
+-- Nullable: rows written before this column existed stay NULL.
+ALTER TABLE crash_reports ADD COLUMN build_mode TEXT;

apps/api-server/migrations/0004_crash_short_id.sql

@@ -0,0 +1,5 @@
+-- User-visible short ID surfaced in the crash dialog and the email summary.
+-- Nullable: rows written before this column existed stay NULL.
+ALTER TABLE crash_reports ADD COLUMN short_id TEXT;
+
+CREATE INDEX idx_crash_reports_short_id ON crash_reports(short_id);

apps/api-server/src/crash-report.test.ts

@@ -76,13 +76,48 @@ describe('POST /crash-report', () => {
     expect(prepareCall).toContain('INSERT INTO crash_reports')
 
     const bindArgs = bindMock.mock.calls[0]
-    // bindArgs: [hashedIp, appVersion, osVersion, arch, signal, topFunction, backtraceTruncated]
+    // bindArgs: [hashedIp, appVersion, osVersion, arch, signal, topFunction, backtraceTruncated, buildMode, shortId]
     expect(bindArgs[0]).toMatch(/^[0-9a-f]{64}$/) // SHA-256 hex
     expect(bindArgs[1]).toBe('1.2.3') // appVersion
     expect(bindArgs[2]).toBe('15.3.1') // osVersion
     expect(bindArgs[3]).toBe('arm64') // arch
     expect(bindArgs[4]).toBe('SIGSEGV') // signal
     expect(bindArgs[5]).toBe('cmdr::sync_status::get_ubiquitous_bool') // topFunction
+    expect(bindArgs[7]).toBeNull() // buildMode (not supplied by validCrashReport)
+    expect(bindArgs[8]).toBeNull() // shortId (not supplied by validCrashReport)
+  })
+
+  it('stores buildMode and shortId when supplied', async () => {
+    const { db, bindMock } = createMockD1()
+    const bindings = createBindings({ TELEMETRY_DB: db })
+
+    const report = { ...validCrashReport, buildMode: 'debug', shortId: 'CRASH-A2345' }
+
+    await postCrashReport(report, bindings)
+
+    const bindArgs = bindMock.mock.calls[0]
+    expect(bindArgs[7]).toBe('debug')
+    expect(bindArgs[8]).toBe('CRASH-A2345')
+  })
+
+  it('returns 400 for invalid buildMode', async () => {
+    const bindings = createBindings()
+    const report = { ...validCrashReport, buildMode: 'staging' }
+
+    const res = await postCrashReport(report, bindings)
+    expect(res.status).toBe(400)
+    const body = await res.json<{ error: string }>()
+    expect(body.error).toBe('Invalid buildMode')
+  })
+
+  it('returns 400 for malformed shortId', async () => {
+    const bindings = createBindings()
+    const report = { ...validCrashReport, shortId: 'CRASH-lowercase' }
+
+    const res = await postCrashReport(report, bindings)
+    expect(res.status).toBe(400)
+    const body = await res.json<{ error: string }>()
+    expect(body.error).toBe('Invalid shortId')
   })
 
   it('extracts the first cmdr frame as topFunction', async () => {

apps/api-server/src/email.ts

@@ -1,15 +1,26 @@
 import { Resend } from 'resend'
 import type { LicenseType } from './license'
 
-export interface CrashSummaryEntry {
-  topFunction: string
-  count: number
-  versions: string[]
-  mostRecent: string
+/**
+ * One row in the crash notification email. The email lists every crash report (no
+ * grouping by `top_function` like the previous incarnation) so each row maps to a
+ * single D1 row, with the short id letting the user trace it back.
+ */
+export interface CrashEmailRow {
+  /** `created_at` in ISO 8601. */
+  when: string
+  /** Friendly env (`'prod'` for release, `'dev'` for debug, `'?'` for unknown). */
+  env: 'prod' | 'dev' | '?'
+  /** `CRASH-XXXXX`, or `'?'` for rows from older clients. */
+  id: string
+  /** `top_function`. */
+  site: string
+  signal: string
+  version: string
 }
 
 interface CrashNotificationParams {
-  crashes: CrashSummaryEntry[]
+  crashes: CrashEmailRow[]
   totalCount: number
   to: string
   resendApiKey: string
@@ -23,10 +34,12 @@ export async function sendCrashNotificationEmail(params: CrashNotificationParams
     .map(
       (entry) => `
         <tr>
-            <td style="padding: 8px 12px; border: 1px solid #e5e7eb; font-family: monospace; font-size: 13px;">${escapeHtml(entry.topFunction)}</td>
-            <td style="padding: 8px 12px; border: 1px solid #e5e7eb; text-align: center;">${String(entry.count)}</td>
-            <td style="padding: 8px 12px; border: 1px solid #e5e7eb; font-size: 13px;">${escapeHtml(entry.versions.join(', '))}</td>
-            <td style="padding: 8px 12px; border: 1px solid #e5e7eb; font-size: 13px;">${escapeHtml(entry.mostRecent)}</td>
+            <td style="padding: 8px 12px; border: 1px solid #e5e7eb; font-size: 13px; white-space: nowrap;">${escapeHtml(entry.when)}</td>
+            <td style="padding: 8px 12px; border: 1px solid #e5e7eb; font-size: 13px; text-align: center;">${escapeHtml(entry.env)}</td>
+            <td style="padding: 8px 12px; border: 1px solid #e5e7eb; font-family: monospace; font-size: 13px;">${escapeHtml(entry.id)}</td>
+            <td style="padding: 8px 12px; border: 1px solid #e5e7eb; font-family: monospace; font-size: 13px;">${escapeHtml(entry.site)}</td>
+            <td style="padding: 8px 12px; border: 1px solid #e5e7eb; font-size: 13px;">${escapeHtml(entry.signal)}</td>
+            <td style="padding: 8px 12px; border: 1px solid #e5e7eb; font-size: 13px;">${escapeHtml(entry.version)}</td>
         </tr>`,
     )
     .join('\n')
@@ -41,16 +54,18 @@ export async function sendCrashNotificationEmail(params: CrashNotificationParams
 <head>
     <meta charset="utf-8">
 </head>
-<body style="font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif; line-height: 1.6; color: #333; max-width: 600px; margin: 0 auto; padding: 20px;">
+<body style="font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif; line-height: 1.6; color: #333; max-width: 720px; margin: 0 auto; padding: 20px;">
     <h2 style="color: #dc2626;">${escapeHtml(subject)}</h2>
 
     <table style="border-collapse: collapse; width: 100%; margin: 16px 0;">
         <thead>
             <tr>
-                <th style="padding: 8px 12px; border: 1px solid #e5e7eb; text-align: left; background: #f9fafb;">Crash site</th>
-                <th style="padding: 8px 12px; border: 1px solid #e5e7eb; text-align: center; background: #f9fafb;">Count</th>
-                <th style="padding: 8px 12px; border: 1px solid #e5e7eb; text-align: left; background: #f9fafb;">Versions</th>
-                <th style="padding: 8px 12px; border: 1px solid #e5e7eb; text-align: left; background: #f9fafb;">Most recent</th>
+                <th style="padding: 8px 12px; border: 1px solid #e5e7eb; text-align: left; background: #f9fafb;">When</th>
+                <th style="padding: 8px 12px; border: 1px solid #e5e7eb; text-align: center; background: #f9fafb;">Env</th>
+                <th style="padding: 8px 12px; border: 1px solid #e5e7eb; text-align: left; background: #f9fafb;">ID</th>
+                <th style="padding: 8px 12px; border: 1px solid #e5e7eb; text-align: left; background: #f9fafb;">Site</th>
+                <th style="padding: 8px 12px; border: 1px solid #e5e7eb; text-align: left; background: #f9fafb;">Signal</th>
+                <th style="padding: 8px 12px; border: 1px solid #e5e7eb; text-align: left; background: #f9fafb;">Version</th>
             </tr>
         </thead>
         <tbody>

apps/api-server/src/scheduled.test.ts

@@ -77,7 +77,7 @@ beforeEach(() => {
 })
 
 describe('handleCrashNotifications', () => {
-  it('sends email for un-notified crash reports', async () => {
+  it('sends one row per un-notified crash report', async () => {
     const responses = new Map<string, unknown>([
       [
         'SELECT id',
@@ -91,6 +91,8 @@ describe('handleCrashNotifications', () => {
               signal: 'SIGSEGV',
               top_function: 'cmdr::sync::run',
               created_at: '2026-03-23T10:00:00Z',
+              build_mode: 'release',
+              short_id: 'CRASH-A2345',
             },
             {
               id: 2,
@@ -100,6 +102,8 @@ describe('handleCrashNotifications', () => {
               signal: 'SIGSEGV',
               top_function: 'cmdr::sync::run',
               created_at: '2026-03-23T11:00:00Z',
+              build_mode: 'debug',
+              short_id: 'CRASH-B6789',
             },
             {
               id: 3,
@@ -109,6 +113,8 @@ describe('handleCrashNotifications', () => {
               signal: 'SIGABRT',
               top_function: 'cmdr_lib::indexer::build',
               created_at: '2026-03-23T12:00:00Z',
+              build_mode: null,
+              short_id: null,
             },
           ],
         },
@@ -125,8 +131,17 @@ describe('handleCrashNotifications', () => {
     expect(emailCall.subject).toBe('Cmdr: 3 new crash reports')
     expect(emailCall.to).toBe('test@example.com')
     expect(emailCall.from).toBe('Cmdr Crash Alerts <noreply@getcmdr.com>')
+    // Per-row rendering — each crash shows up with its top_function and short id.
     expect(emailCall.html).toContain('cmdr::sync::run')
     expect(emailCall.html).toContain('cmdr_lib::indexer::build')
+    expect(emailCall.html).toContain('CRASH-A2345')
+    expect(emailCall.html).toContain('CRASH-B6789')
+    // Env column shows friendly labels.
+    expect(emailCall.html).toContain('>prod<')
+    expect(emailCall.html).toContain('>dev<')
+    // Row 3 has neither build_mode nor short_id — both render as `?`.
+    const questionMarkCells = emailCall.html.match(/>\?</g)?.length ?? 0
+    expect(questionMarkCells).toBeGreaterThanOrEqual(2)
 
     // Verify rows were marked as notified (UPDATE query was called)
     const updateCall = calls.find((c) => c.sql.includes('UPDATE crash_reports'))
@@ -153,6 +168,8 @@ describe('handleCrashNotifications', () => {
               signal: 'SIGSEGV',
               top_function: 'cmdr::sync::run',
               created_at: '2026-03-23T10:00:00Z',
+              build_mode: 'release',
+              short_id: 'CRASH-A2345',
             },
           ],
         },

apps/api-server/src/scheduled.ts

@@ -1,16 +1,26 @@
-import { sendCrashNotificationEmail, sendDbSizeAlert, type CrashSummaryEntry } from './email'
+import { sendCrashNotificationEmail, sendDbSizeAlert, type CrashEmailRow } from './email'
 import type { Bindings } from './types'
 import { recomputeTotal, tryEvict, EVICTION_HIGH_WATERMARK } from './error-report-eviction'
 import { postEvictionNotification } from './discord'
 
 const dbSizeThresholdBytes = 100 * 1024 * 1024 // 100 MB
 
+/** Map the DB `build_mode` column to the friendly `prod`/`dev` label users see. */
+function buildModeToEnv(buildMode: string | null | undefined): 'prod' | 'dev' | '?' {
+  if (buildMode === 'release') return 'prod'
+  if (buildMode === 'debug') return 'dev'
+  return '?'
+}
+
 async function handleCrashNotifications(env: Bindings): Promise<void> {
   if (!env.CRASH_NOTIFICATION_EMAIL || !env.RESEND_API_KEY) return
 
+  // One row per crash, newest first. No grouping — the email shows every report.
   const { results } = await env.TELEMETRY_DB.prepare(
-    `SELECT id, app_version, os_version, arch, signal, top_function, created_at
-         FROM crash_reports WHERE notified_at IS NULL`,
+    `SELECT id, app_version, os_version, arch, signal, top_function, created_at, build_mode, short_id
+         FROM crash_reports
+         WHERE notified_at IS NULL
+         ORDER BY created_at DESC`,
   ).all<{
     id: number
     app_version: string
@@ -19,32 +29,19 @@ async function handleCrashNotifications(env: Bindings): Promise<void> {
     signal: string
     top_function: string
     created_at: string
+    build_mode: string | null
+    short_id: string | null
   }>()
 
   if (results.length === 0) return
 
-  // Group by top_function
-  const grouped = new Map<string, { count: number; versions: Set<string>; mostRecent: string }>()
-  for (const row of results) {
-    const existing = grouped.get(row.top_function)
-    if (existing) {
-      existing.count++
-      existing.versions.add(row.app_version)
-      if (row.created_at > existing.mostRecent) existing.mostRecent = row.created_at
-    } else {
-      grouped.set(row.top_function, {
-        count: 1,
-        versions: new Set([row.app_version]),
-        mostRecent: row.created_at,
-      })
-    }
-  }
-
-  const crashes: CrashSummaryEntry[] = [...grouped.entries()].map(([topFunction, data]) => ({
-    topFunction,
-    count: data.count,
-    versions: [...data.versions],
-    mostRecent: data.mostRecent,
+  const crashes: CrashEmailRow[] = results.map((row) => ({
+    when: row.created_at,
+    env: buildModeToEnv(row.build_mode),
+    id: row.short_id ?? '?',
+    site: row.top_function,
+    signal: row.signal,
+    version: row.app_version,
   }))
 
   const ids = results.map((r) => r.id)

apps/api-server/src/telemetry.ts

@@ -13,10 +13,16 @@ interface CrashReport {
   osVersion: string
   arch: string
   signal: string
+  /** Optional. `"release"` or `"debug"`; older clients don't set it (stored as NULL). */
+  buildMode?: 'release' | 'debug'
+  /** Optional. `CRASH-XXXXX` short ID generated by the desktop client. */
+  shortId?: string
   backtraceFrames?: string[]
   [key: string]: unknown
 }
 
+const crashShortIdPattern = /^CRASH-[23456789ABCDEFGHJKMNPQRSTUVWXYZ]{5}$/
+
 /** Extract the first app-code frame from a backtrace (contains `cmdr` or `cmdr_lib`). */
 function extractTopFunction(frames: string[] | undefined): string {
   if (!frames || !Array.isArray(frames)) return 'unknown'
@@ -28,6 +34,31 @@ function extractTopFunction(frames: string[] | undefined): string {
   return 'unknown'
 }
 
+/**
+ * Validate the runtime shape of a `POST /crash-report` body. Returns `null` if the
+ * body is well-formed; otherwise returns the error message to surface as 400. We
+ * type the input as `Record<string, unknown>` (not `CrashReport`) so the optional-
+ * field checks aren't statically narrowed away — values arrive from `JSON.parse`
+ * and can be any shape an attacker chooses.
+ */
+function validateCrashReportShape(report: Record<string, unknown>): string | null {
+  for (const field of crashReportRequiredFields) {
+    const value = report[field]
+    if (typeof value !== 'string' || value.length === 0) {
+      return `Missing required field: ${field}`
+    }
+  }
+  const buildMode = report.buildMode
+  if (buildMode !== undefined && buildMode !== 'release' && buildMode !== 'debug') {
+    return 'Invalid buildMode'
+  }
+  const shortId = report.shortId
+  if (shortId !== undefined && (typeof shortId !== 'string' || !crashShortIdPattern.test(shortId))) {
+    return 'Invalid shortId'
+  }
+  return null
+}
+
 telemetry.post('/crash-report', async (c) => {
   // Reject oversized payloads before parsing
   const contentLength = c.req.header('content-length')
@@ -46,19 +77,21 @@ telemetry.post('/crash-report', async (c) => {
     return c.json({ error: 'Report too large' }, 400)
   }
 
-  let report: CrashReport
+  let rawReport: unknown
   try {
-    report = JSON.parse(rawBody) as CrashReport
+    rawReport = JSON.parse(rawBody)
   } catch {
     return c.json({ error: 'Invalid JSON' }, 400)
   }
+  if (!rawReport || typeof rawReport !== 'object') {
+    return c.json({ error: 'Invalid JSON' }, 400)
+  }
 
-  // Validate required fields
-  for (const field of crashReportRequiredFields) {
-    if (typeof report[field] !== 'string' || report[field].length === 0) {
-      return c.json({ error: `Missing required field: ${field}` }, 400)
-    }
+  const validationError = validateCrashReportShape(rawReport as Record<string, unknown>)
+  if (validationError) {
+    return c.json({ error: validationError }, 400)
   }
+  const report = rawReport as CrashReport
 
   // Hash IP with daily salt for deduplication (same pattern as update-check)
   const ip = c.req.header('cf-connecting-ip') ?? c.req.header('x-forwarded-for') ?? 'unknown'
@@ -69,12 +102,23 @@ telemetry.post('/crash-report', async (c) => {
   const topFunction = extractTopFunction(report.backtraceFrames)
   const backtraceTruncated = JSON.stringify(report.backtraceFrames ?? []).slice(0, maxBacktraceBytes)
 
-  // Write to D1 (fire-and-forget)
+  // Write to D1 (fire-and-forget). `build_mode` and `short_id` are nullable —
+  // rows from older clients stay NULL.
   const dbWrite = c.env.TELEMETRY_DB.prepare(
-    `INSERT INTO crash_reports (hashed_ip, app_version, os_version, arch, signal, top_function, backtrace)
-         VALUES (?, ?, ?, ?, ?, ?, ?)`,
+    `INSERT INTO crash_reports (hashed_ip, app_version, os_version, arch, signal, top_function, backtrace, build_mode, short_id)
+         VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)`,
   )
-    .bind(hashedIp, report.appVersion, report.osVersion, report.arch, report.signal, topFunction, backtraceTruncated)
+    .bind(
+      hashedIp,
+      report.appVersion,
+      report.osVersion,
+      report.arch,
+      report.signal,
+      topFunction,
+      backtraceTruncated,
+      report.buildMode ?? null,
+      report.shortId ?? null,
+    )
     .run()
     .catch(() => {}) // Don't let D1 failure block the response
 

apps/desktop/src-tauri/src/crash_reporter/CLAUDE.md

@@ -47,6 +47,10 @@ Both paths write to `crash-report.json` in the app data dir (same dir as `settin
 - Sanitized panic message
 - Active feature flags (booleans/enums only: `indexing.enabled`, `ai.provider`, `developer.mcpEnabled`,
   `developer.verboseLogging`)
+- `buildMode` (`"release"` or `"debug"`, from `cfg!(debug_assertions)`) — lets the api server distinguish dev-run
+  crashes from production ones in the email summary
+- `shortId` (`CRASH-XXXXX`) — generated at crash-file-write time via [`crate::short_id::generate("CRASH")`]
+  (shared with error reports). Shown to the user in the next-launch dialog so they can reference the report.
 
 ## What we never send