@gotcos/glasses-server 6.6.0 → 6.8.0

package/server/routes/meeting.ts

@@ -0,0 +1,329 @@
+// POST /api/meeting/save — finalize an existing transcribe-stream session into
+// the standalone public meeting store. The live transcript and chunk metadata
+// are durable before the session is closed; batch improvement runs afterward.
+
+import { rmSync } from 'node:fs'
+import { Router } from 'express'
+import { emitDisplay } from '../lib/display-bus.js'
+import { cleanTranscriptLines } from '../lib/hallucination-filter.js'
+import {
+  getMeetingStore,
+  MeetingStore,
+  MeetingStoreError,
+  type SavedMeeting,
+} from '../lib/meeting-store.js'
+import {
+  canDeletePendingBatchAudio,
+  persistBatchDecisionSidecar,
+  replaceMeetingTranscriptAtomic,
+} from '../lib/meeting-batch-persistence.js'
+import { runMeetingBatchPipeline } from '../lib/meeting-batch-transcribe.js'
+import {
+  selectBatchTranscriptForPersistence,
+  type BatchTranscription,
+} from '../lib/batch-transcript-quality.js'
+import {
+  analyzeTranscriptGaps,
+  deleteSession,
+  drainSessionAudioWrites,
+  getSessionChunkEntries,
+  getSessionChunks,
+  getSessionProviderCandidates,
+  getSessionStartTime,
+  getSessionTranscript,
+  hasSessionAudio,
+  moveSessionAudioToPending,
+  type IndexedTranscriptChunk,
+  type ProviderCandidateRecord,
+  type TranscriptChunk,
+  type TranscriptGapReport,
+} from './transcribe-stream.js'
+
+interface MeetingSessionSource {
+  getTranscript(sessionId: string): string | null
+  getStartTime(sessionId: string): number | null
+  getChunks(sessionId: string): TranscriptChunk[] | null
+  getChunkEntries(sessionId: string): IndexedTranscriptChunk[] | null
+  getProviderCandidates(sessionId: string): Record<string, ProviderCandidateRecord>
+  getIntegrity(sessionId: string): TranscriptGapReport | null
+  drainAudioWrites(sessionId: string): Promise<void>
+  hasAudio(sessionId: string): boolean
+  moveAudioToPending(sessionId: string): string | null
+  delete(sessionId: string, options?: { preserveAudio?: boolean }): void
+}
+
+export interface MeetingRouteDependencies {
+  store?: MeetingStore
+  sessions?: MeetingSessionSource
+  runBatch?: (
+    audioDir: string,
+    entries: IndexedTranscriptChunk[],
+    streamingWordCount: number,
+  ) => Promise<BatchTranscription>
+  scheduleBackground?: (task: Promise<void>) => void
+  emit?: typeof emitDisplay
+}
+
+const defaultSessionSource: MeetingSessionSource = {
+  getTranscript: sessionId => getSessionTranscript(sessionId, { withGaps: true }),
+  getStartTime: getSessionStartTime,
+  getChunks: getSessionChunks,
+  getChunkEntries: getSessionChunkEntries,
+  getProviderCandidates: getSessionProviderCandidates,
+  getIntegrity: analyzeTranscriptGaps,
+  drainAudioWrites: drainSessionAudioWrites,
+  hasAudio: hasSessionAudio,
+  moveAudioToPending: moveSessionAudioToPending,
+  delete: deleteSession,
+}
+
+function countWords(text: string): number {
+  return text.trim().split(/\s+/).filter(Boolean).length
+}
+
+function cleanFinalTranscript(transcript: string): string {
+  try {
+    return process.env.COS_WHISPER_STRIP_BRAND_URLS === '0'
+      ? transcript
+      : cleanTranscriptLines(transcript)
+  } catch {
+    return transcript
+  }
+}
+
+function publicSaveResponse(saved: SavedMeeting, replayed = false): Record<string, unknown> {
+  const integrity = saved.transferIntegrity ?? null
+  const missingCount = integrity?.missingIndices.length ?? 0
+  const completenessPct = integrity
+    ? Math.floor(integrity.completeness * 1_000) / 10
+    : 100
+  return {
+    saved: true,
+    // Keep the build199 string field without leaking an absolute host path.
+    filepath: `recordings/${saved.month}/${saved.filename}`,
+    filename: saved.filename,
+    durationMin: saved.durationMin,
+    domain: saved.domain,
+    transcriptionQuality: 'streaming',
+    ...(replayed ? { replayed: true } : {}),
+    transferIntegrity: integrity ? {
+      completeness: completenessPct,
+      received: integrity.received,
+      expected: integrity.expected,
+      missingChunks: missingCount,
+      missingIndices: integrity.missingIndices.slice(0, 50),
+    } : null,
+  }
+}
+
+export function createMeetingRouter(deps: MeetingRouteDependencies = {}): Router {
+  const store = deps.store ?? getMeetingStore()
+  const sessions = deps.sessions ?? defaultSessionSource
+  const runBatch = deps.runBatch ?? runMeetingBatchPipeline
+  const scheduleBackground = deps.scheduleBackground ?? (task => { void task })
+  const emit = deps.emit ?? emitDisplay
+  const router = Router()
+  const savingSessions = new Set<string>()
+
+  router.post('/meeting/save', async (req, res) => {
+    let lockedSessionId: string | null = null
+    try {
+      const body = req.body as Record<string, unknown> | undefined
+      const sessionId = typeof body?.sessionId === 'string' ? body.sessionId : ''
+      if (!sessionId) {
+        res.status(400).json({ error: 'sessionId required', reason: 'missing_session_id' })
+        return
+      }
+      if (!/^[A-Za-z0-9:_-]{3,96}$/.test(sessionId)) {
+        res.status(400).json({ error: 'Invalid sessionId', reason: 'invalid_session_id' })
+        return
+      }
+      if (body?.title !== undefined && typeof body.title !== 'string') {
+        res.status(400).json({ error: 'Invalid title', reason: 'invalid_title' })
+        return
+      }
+      if (body?.domain !== undefined && typeof body.domain !== 'string') {
+        res.status(400).json({ error: 'Invalid domain', reason: 'invalid_domain' })
+        return
+      }
+
+      // A response can be lost after both durable files were committed. Find
+      // the sidecar by session ID so client retry/restart is idempotent.
+      const alreadySaved = store.findBySessionId(sessionId)
+      if (alreadySaved) {
+        res.set('Cache-Control', 'private, no-store')
+        res.json(publicSaveResponse(alreadySaved, true))
+        return
+      }
+      if (savingSessions.has(sessionId)) {
+        res.status(409).json({ error: 'Meeting save already in progress', reason: 'save_in_progress' })
+        return
+      }
+      savingSessions.add(sessionId)
+      lockedSessionId = sessionId
+
+      const transcript = sessions.getTranscript(sessionId)
+      if (!transcript?.trim()) {
+        res.status(404).json({
+          error: `No transcript found for session ${sessionId}`,
+          reason: 'session_not_found',
+        })
+        return
+      }
+
+      const chunks = sessions.getChunks(sessionId) ?? []
+      const chunkEntries = sessions.getChunkEntries(sessionId)
+        ?? chunks.map((chunk, chunkIndex) => ({ chunkIndex, chunk }))
+      const startTime = sessions.getStartTime(sessionId) ?? Date.now()
+      const durationFromTimeline = chunks.reduce(
+        (maximum, chunk) => Math.max(maximum, chunk?.elapsed ?? 0),
+        0,
+      )
+      const durationMs = durationFromTimeline > 0
+        ? durationFromTimeline
+        : Math.max(0, Date.now() - startTime)
+      const integrity = sessions.getIntegrity(sessionId)
+
+      // Initial canonical text + structured metadata are published before any
+      // live state is removed or background work is scheduled.
+      const saved = store.save({
+        sessionId,
+        title: body?.title as string | undefined,
+        domain: body?.domain as string | undefined,
+        transcript: cleanFinalTranscript(transcript),
+        startTime,
+        durationMs,
+        chunks,
+        chunkEntries,
+        providerCandidates: sessions.getProviderCandidates(sessionId),
+        transferIntegrity: integrity,
+      })
+
+      // Wait for every raw-WAV write before rename. If any write failed, retain
+      // surviving audio for recovery but do not run an incomplete batch.
+      let audioWritesReady = true
+      try {
+        await sessions.drainAudioWrites(sessionId)
+      } catch (error) {
+        audioWritesReady = false
+        console.warn(
+          `[meeting/save] One or more raw audio writes failed for ${sessionId}: `
+          + `${error instanceof Error ? error.message : String(error)}`,
+        )
+      }
+      const hadSessionAudio = sessions.hasAudio(sessionId)
+      // drainAudioWrites uses allSettled, so even its error path has no live
+      // writes. Move surviving evidence to the normal two-hour pending store,
+      // but do not batch an incomplete capture.
+      const pendingAudioDir = hadSessionAudio ? sessions.moveAudioToPending(sessionId) : null
+      const preserveSourceAudio = hadSessionAudio && !pendingAudioDir
+      sessions.delete(sessionId, { preserveAudio: preserveSourceAudio })
+      if (preserveSourceAudio) {
+        console.warn(`[meeting/save] Source audio for ${sessionId} retained after failed pending handoff`)
+      }
+
+      try {
+        emit({
+          type: 'recording_stop',
+          data: {
+            sessionId,
+            filename: saved.filename,
+            durationMin: saved.durationMin,
+            domain: saved.domain,
+          },
+        })
+      } catch (error) {
+        console.warn('[meeting/save] Display notification failed after durable save:', error)
+      }
+
+      res.set('Cache-Control', 'private, no-store')
+      res.json(publicSaveResponse(saved))
+
+      if (audioWritesReady && pendingAudioDir && chunkEntries.length > 0) {
+        const task = finalizeBatch({
+          audioDir: pendingAudioDir,
+          entries: chunkEntries.map(entry => ({ ...entry, chunk: { ...entry.chunk } })),
+          streamingWordCount: countWords(transcript),
+          meetingPath: saved.filepath,
+          sidecarPath: saved.sidecarPath,
+          runBatch,
+        }).catch(error => {
+          // Raw audio deliberately remains for the existing two-hour cleanup.
+          console.error(
+            `[meeting/save] Batch finalization failed for ${sessionId}: `
+            + `${error instanceof Error ? error.message : String(error)}`,
+          )
+        })
+        scheduleBackground(task)
+      }
+    } catch (error) {
+      if (error instanceof MeetingStoreError) {
+        res.status(error.status).json({ error: error.message, reason: error.code })
+        return
+      }
+      console.error('[meeting/save] Finalization failed:', error)
+      res.status(500).json({ error: 'Meeting save failed', reason: 'meeting_save_error' })
+    } finally {
+      if (lockedSessionId) savingSessions.delete(lockedSessionId)
+    }
+  })
+
+  return router
+}
+
+async function finalizeBatch(options: {
+  audioDir: string
+  entries: IndexedTranscriptChunk[]
+  streamingWordCount: number
+  meetingPath: string
+  sidecarPath: string
+  runBatch: NonNullable<MeetingRouteDependencies['runBatch']>
+}): Promise<void> {
+  const result = await options.runBatch(
+    options.audioDir,
+    options.entries,
+    options.streamingWordCount,
+  )
+  let transcriptApplied = false
+  let metadataPersisted = false
+  let persistedResult = result
+
+  if (result.transcriptionQuality === 'batch' && result.batchTranscript) {
+    const selected = selectBatchTranscriptForPersistence(result.batchTranscript, result.batchSegments)
+    const canonicalText = cleanFinalTranscript(selected.text)
+    if (canonicalText.trim()) {
+      transcriptApplied = replaceMeetingTranscriptAtomic(options.meetingPath, canonicalText)
+    } else {
+      console.error('[meeting/save] Accepted batch candidate cleaned to empty; canonical text retained')
+    }
+    // Metadata records the exact selected text that became canonical, while
+    // batchSegments retain the full diagnostic evidence.
+    persistedResult = { ...result, batchTranscript: canonicalText }
+  } else if (result.qualityReport) {
+    console.warn(
+      `[meeting/save] Batch candidate rejected (${result.qualityReport.reason}); `
+      + 'canonical streaming transcript retained',
+    )
+  }
+
+  try {
+    metadataPersisted = persistBatchDecisionSidecar(
+      options.sidecarPath,
+      persistedResult,
+      transcriptApplied,
+    )
+  } catch (error) {
+    console.error(
+      '[meeting/save] Batch decision metadata was not durable:',
+      error instanceof Error ? error.message : String(error),
+    )
+  }
+
+  if (canDeletePendingBatchAudio(transcriptApplied, metadataPersisted)) {
+    rmSync(options.audioDir, { recursive: true, force: true })
+  } else {
+    console.warn('[meeting/save] Pending raw audio retained for bounded two-hour cleanup')
+  }
+}
+
+export const meetingRouter = createMeetingRouter()

package/server/routes/meetings.ts

@@ -0,0 +1,66 @@
+// Standalone meeting archive backed only by the public server's private data
+// directory. No COS operations paths, classifiers, or user-specific stores.
+
+import { Router } from 'express'
+import { getMeetingStore, MeetingStore, MeetingStoreError } from '../lib/meeting-store.js'
+
+export function createMeetingsRouter(store: MeetingStore = getMeetingStore()): Router {
+  const router = Router()
+
+  // GET /api/meetings?limit=20&domain=all
+  router.get('/meetings', (req, res) => {
+    try {
+      const rawLimit = typeof req.query.limit === 'string' ? Number.parseInt(req.query.limit, 10) : 20
+      const limit = Number.isFinite(rawLimit) ? rawLimit : 20
+      const domain = typeof req.query.domain === 'string' ? req.query.domain : 'all'
+      res.set('Cache-Control', 'private, no-store')
+      res.json({ meetings: store.list({ limit, domain }) })
+    } catch (error) {
+      sendMeetingStoreError(res, error)
+    }
+  })
+
+  // Query-form detail is convenient for generic API consumers. Register the
+  // literal route before the build199 dynamic compatibility route.
+  router.get('/meetings/detail', (req, res) => {
+    try {
+      const domain = typeof req.query.domain === 'string' ? req.query.domain : ''
+      const month = typeof req.query.month === 'string' ? req.query.month : ''
+      const filename = typeof req.query.filename === 'string' ? req.query.filename : ''
+      if (!domain || !month || !filename) {
+        res.status(400).json({ error: 'domain, month, and filename are required', reason: 'invalid_meeting_ref' })
+        return
+      }
+      res.set('Cache-Control', 'private, no-store')
+      res.json(store.detail(domain, month, filename))
+    } catch (error) {
+      sendMeetingStoreError(res, error)
+    }
+  })
+
+  // Build199 compatibility: detail requests carry the list row's domain even
+  // though standalone files all live in one fixed recordings/YYYY-MM store.
+  router.get('/meetings/:domain/:month/:filename', (req, res) => {
+    try {
+      res.set('Cache-Control', 'private, no-store')
+      res.json(store.detail(req.params.domain, req.params.month, req.params.filename))
+    } catch (error) {
+      sendMeetingStoreError(res, error)
+    }
+  })
+
+  return router
+}
+
+function sendMeetingStoreError(
+  res: { status: (status: number) => { json: (body: unknown) => unknown } },
+  error: unknown,
+): unknown {
+  if (error instanceof MeetingStoreError) {
+    return res.status(error.status).json({ error: error.message, reason: error.code })
+  }
+  console.error('[meetings] Store read failed:', error)
+  return res.status(500).json({ error: 'Meeting store unavailable', reason: 'meeting_store_error' })
+}
+
+export const meetingsRouter = createMeetingsRouter()

package/server/routes/prompt-drafts.ts

@@ -0,0 +1,276 @@
+import { Router } from 'express'
+import { createHash } from 'node:crypto'
+import type { Response } from 'express'
+import { existsSync, mkdirSync, readFileSync } from 'node:fs'
+import { resolve, dirname } from 'node:path'
+import {
+  createPromptDraft,
+  loadPromptDraftMeta,
+  savePromptDraftChunk,
+  readPromptDraftChunks,
+  markPromptDraftFinalized,
+  markPromptDraftChunkTranscript,
+  markPromptDraftError,
+  getMissingChunkIndexes,
+  prunePromptDrafts,
+  type PromptDraftTranscriptRecord,
+} from '../lib/prompt-draft-store.js'
+import {
+  transcribeAudioBuffer,
+  resolveTranscribeMode,
+  NoSpeechDetectedError,
+  OpenAIWhisperBudgetExhaustedError,
+  TranscriptionUnavailableError,
+} from '../lib/transcribe-audio.js'
+import {
+  stripInlineHallucinationsOneShot,
+  stripInlineHallucinations,
+  stripPromptDictationArtifacts,
+  isFullHallucination,
+  isBrandUrlOnly,
+  clearSessionHallucinationState,
+  applyNegativeRules,
+} from '../lib/hallucination-filter.js'
+import { applyCorrections } from '../lib/whisper-local.js'
+import { autoCleanDictation, AUTOCLEAN_MAX_CHARS } from '../lib/dictation-clean.js'
+import { getVocabulary } from '../lib/profile.js'
+import { createBreaker } from '../lib/claude-circuit.js'
+import { logTokenAudit } from '../lib/token-audit.js'
+import { atomicWriteFileSync } from '../lib/atomic-fs.js'
+import { dataPath } from '../lib/data-dir.js'
+
+export const promptDraftsRouter = Router()
+
+const MAX_CHUNK_BYTES = 25 * 1024 * 1024
+const MAX_DRAFT_BYTES = 256 * 1024 * 1024
+const MAX_CHUNKS = 600
+const chunkTranscriptJobs = new Map<string, Promise<string>>()
+const finalizeJobs = new Map<string, Promise<any>>()
+let warmTail: Promise<void> = Promise.resolve()
+
+const autoCleanBreaker = createBreaker({ label: 'dictation-autoclean' })
+const autoCleanCountFile = () => process.env.COS_DICTATION_AUTOCLEAN_COUNT_FILE || dataPath('.dictation_autoclean_count.json')
+const autoCleanDefaultEnabled = () => ['1', 'true', 'on'].includes((process.env.COS_DICTATION_AUTOCLEAN ?? '').toLowerCase())
+const autoCleanDailyCap = () => {
+  const value = Number.parseInt(process.env.COS_DICTATION_AUTOCLEAN_MAX_PER_DAY || '200', 10)
+  return Number.isFinite(value) && value > 0 ? value : 200
+}
+function autoCleanCountToday(): number {
+  try {
+    const raw = JSON.parse(readFileSync(autoCleanCountFile(), 'utf-8'))
+    if (raw?.date === new Date().toISOString().slice(0, 10) && Number.isFinite(raw?.count)) return raw.count
+  } catch {}
+  return 0
+}
+function recordAutoCleanCall(): void {
+  try {
+    const file = autoCleanCountFile()
+    if (!existsSync(dirname(file))) mkdirSync(dirname(file), { recursive: true })
+    atomicWriteFileSync(file, JSON.stringify({ date: new Date().toISOString().slice(0, 10), count: autoCleanCountToday() + 1 }), { mode: 0o600 })
+  } catch {}
+}
+
+interface AutoCleanRequest { enabled?: boolean; model?: 'haiku' | 'sonnet' }
+function routeAutoClean(req: { body?: any; query?: any }): AutoCleanRequest {
+  const rawEnabled = req.body?.autoclean ?? req.query?.autoclean
+  const enabled = rawEnabled === undefined ? undefined : ['1', 'true', 'on'].includes(String(rawEnabled).toLowerCase())
+  const rawModel = String(req.body?.autocleanModel ?? req.query?.autocleanModel ?? '').toLowerCase()
+  return { enabled, model: rawModel === 'sonnet' ? 'sonnet' : rawModel === 'haiku' ? 'haiku' : undefined }
+}
+
+async function cleanOutboundDictation(text: string, opts: AutoCleanRequest & { signal?: AbortSignal }): Promise<string> {
+  let cleaned = applyNegativeRules(applyCorrections(text)).replace(/\s+/g, ' ').trim() || text
+  if (!(opts.enabled ?? autoCleanDefaultEnabled())) return cleaned
+  if (cleaned.length > AUTOCLEAN_MAX_CHARS || autoCleanBreaker.isOpen() || autoCleanCountToday() >= autoCleanDailyCap()) return cleaned
+  const startedAt = Date.now()
+  const model = opts.model === 'sonnet' ? 'sonnet' : 'haiku'
+  recordAutoCleanCall()
+  try {
+    const polished = (await autoCleanDictation(cleaned, getVocabulary(), { model, signal: opts.signal })).trim()
+    autoCleanBreaker.recordSuccess()
+    logTokenAudit({
+      source: 'g2-dictation-autoclean', model, inputChars: cleaned.length, outputChars: polished.length,
+      durationMs: Date.now() - startedAt, caller: 'dictation_autoclean',
+    })
+    return polished || cleaned
+  } catch (err: any) {
+    autoCleanBreaker.recordFailure()
+    console.warn(`[prompt-draft] auto-clean failed (glossary-only): ${err?.message ?? err}`)
+    return cleaned
+  }
+}
+
+async function readRawBody(req: AsyncIterable<Buffer | Uint8Array | string>): Promise<Buffer> {
+  const chunks: Buffer[] = []
+  let total = 0
+  for await (const chunk of req) {
+    const buffer = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk)
+    total += buffer.length
+    if (total > MAX_CHUNK_BYTES) throw Object.assign(new Error('audio chunk too large'), { status: 413 })
+    chunks.push(buffer)
+  }
+  return Buffer.concat(chunks)
+}
+
+function routeMode(req: { body?: { mode?: string }; query?: { mode?: string | string[] } }) {
+  return resolveTranscribeMode(
+    (typeof req.body?.mode === 'string' ? req.body.mode : undefined) ??
+    (typeof req.query?.mode === 'string' ? req.query.mode : undefined),
+  )
+}
+
+const sessionId = (draftId: string) => `prompt-draft:${draftId}`
+const audioHash = (audio: Buffer) => createHash('sha256').update(audio).digest('hex')
+function isCurrentChunk(draftId: string, chunkIndex: number, audio: Buffer): boolean {
+  try {
+    return Boolean(readPromptDraftChunks(draftId).find(chunk => chunk.chunkIndex === chunkIndex)?.audioBuffer.equals(audio))
+  } catch {
+    return false
+  }
+}
+function sanitizeTranscript(draftId: string, text: string, learnInline = true): string {
+  const artifactCleaned = stripPromptDictationArtifacts(text).trim()
+  if (isBrandUrlOnly(artifactCleaned)) return ''
+  const oneShot = stripInlineHallucinationsOneShot(artifactCleaned).trim()
+  const cleaned = learnInline ? stripInlineHallucinations(oneShot, sessionId(draftId)).trim() : oneShot
+  return !cleaned || isFullHallucination(cleaned) ? '' : cleaned
+}
+
+async function sendDraftError(res: Response, draftId: string, err: any): Promise<void> {
+  if (err instanceof NoSpeechDetectedError) return void res.status(204).send()
+  if (err instanceof OpenAIWhisperBudgetExhaustedError) {
+    await markPromptDraftError(draftId, err.message)
+    return void res.status(503).json({ error: err.message, reason: 'openai_whisper_budget_exhausted', spent_today_usd: err.spentTodayUsd, cap_usd: err.capUsd })
+  }
+  if (err instanceof TranscriptionUnavailableError) {
+    await markPromptDraftError(draftId, err.message)
+    return void res.status(err.status).json({ error: err.message, reason: err.reason, retryable: true, draftPreserved: true })
+  }
+  await markPromptDraftError(draftId, err.message).catch(() => null)
+  res.status(err.status ?? 500).json({ error: err.message })
+}
+
+async function transcribeChunk(draftId: string, chunkIndex: number, audio: Buffer, mode: 'hq' | 'fast', purpose: 'warm' | 'final'): Promise<string> {
+  const hash = audioHash(audio)
+  const key = `${draftId}:${chunkIndex}:${purpose}:${mode}:${hash}`
+  const existing = chunkTranscriptJobs.get(key)
+  if (existing) return existing
+  const job = (async () => {
+    try {
+      const result = await transcribeAudioBuffer(audio, { mode, policy: purpose === 'warm' ? 'local-only' : 'automatic' })
+      if (!isCurrentChunk(draftId, chunkIndex, audio)) return ''
+      const text = sanitizeTranscript(draftId, result.text)
+      const record: PromptDraftTranscriptRecord = {
+        text, hash, requestedMode: result.requestedMode, actualQuality: result.actualQuality,
+        backend: result.backend, degraded: result.degraded,
+      }
+      await markPromptDraftChunkTranscript(draftId, chunkIndex, record, purpose)
+      console.log(`[prompt-draft] chunk ${draftId}/${chunkIndex}: ${result.elapsedMs.toFixed(1)}ms | ${result.backend} | ${text.length} chars`)
+      return text
+    } catch (err) {
+      if (err instanceof NoSpeechDetectedError) {
+        await markPromptDraftChunkTranscript(draftId, chunkIndex, {
+          text: '', hash, requestedMode: mode, actualQuality: mode, backend: 'no-speech', degraded: false,
+        }, purpose)
+        return ''
+      }
+      throw err
+    } finally {
+      chunkTranscriptJobs.delete(key)
+    }
+  })()
+  chunkTranscriptJobs.set(key, job)
+  return job
+}
+
+async function finalizeDraft(draftId: string, mode: 'hq' | 'fast', autoClean: AutoCleanRequest, signal?: AbortSignal) {
+  const meta = loadPromptDraftMeta(draftId)
+  if (!meta) throw Object.assign(new Error('draft not found'), { status: 404 })
+  const texts: string[] = []
+  for (const chunk of readPromptDraftChunks(draftId)) {
+    try {
+      const current = loadPromptDraftMeta(draftId)
+      const cached = current?.finalTranscripts?.[String(chunk.chunkIndex)] ?? current?.warmTranscripts?.[String(chunk.chunkIndex)]
+      const reusable = Boolean(cached && cached.hash === audioHash(chunk.audioBuffer) && (mode === 'fast' ? cached.actualQuality === 'fast' : cached.actualQuality === 'hq'))
+      const raw = reusable ? cached!.text : await transcribeChunk(draftId, chunk.chunkIndex, chunk.audioBuffer, mode, 'final')
+      const text = sanitizeTranscript(draftId, raw, !reusable)
+      if (text.trim()) texts.push(text.trim())
+    } catch (err) {
+      if (err instanceof NoSpeechDetectedError) continue
+      throw err
+    }
+  }
+  const text = texts.join(' ').replace(/\s+/g, ' ').trim()
+  if (!text) {
+    await markPromptDraftError(draftId, 'No speech detected')
+    throw new NoSpeechDetectedError()
+  }
+  const finalText = await cleanOutboundDictation(text, { ...autoClean, signal })
+  const finalized = await markPromptDraftFinalized(draftId, finalText)
+  return { draftId, text: finalText, recovered: true, chunkCount: finalized.receivedChunkIndexes.length, missingChunks: getMissingChunkIndexes(finalized), expiresAt: finalized.expiresAt }
+}
+
+const prunedAtBoot = prunePromptDrafts()
+if (prunedAtBoot) console.log(`[prompt-draft] pruned ${prunedAtBoot} expired draft(s)`)
+const pruneTimer = setInterval(() => prunePromptDrafts(), 60 * 60 * 1000)
+pruneTimer.unref?.()
+
+promptDraftsRouter.post('/prompt-drafts/start', (req, res) => {
+  const requestedId = typeof req.body?.recoveryId === 'string' ? req.body.recoveryId : undefined
+  const meta = createPromptDraft(requestedId)
+  res.json({ draftId: meta.draftId, recoveryId: requestedId ?? meta.draftId, remapped: Boolean(requestedId && requestedId !== meta.draftId), expiresAt: meta.expiresAt, status: meta.status })
+})
+
+promptDraftsRouter.post('/prompt-drafts/:draftId/chunks', async (req, res) => {
+  try {
+    const raw = Array.isArray(req.query.chunkIndex) ? req.query.chunkIndex[0] : req.query.chunkIndex
+    const chunkIndex = Number(raw)
+    if (!Number.isInteger(chunkIndex) || chunkIndex < 0 || chunkIndex >= MAX_CHUNKS) return res.status(400).json({ error: 'invalid chunkIndex' })
+    const audio = await readRawBody(req)
+    if (audio.length < 44) return res.status(400).json({ error: 'audio too short' })
+    const before = loadPromptDraftMeta(req.params.draftId)
+    if (!before) return res.status(404).json({ error: 'draft not found' })
+    const existingBytes = before.chunkBytes[String(chunkIndex)] ?? 0
+    const nextTotal = Object.values(before.chunkBytes).reduce((sum, bytes) => sum + bytes, 0) - existingBytes + audio.length
+    if (nextTotal > MAX_DRAFT_BYTES) return res.status(413).json({ error: 'prompt draft too large' })
+    const meta = await savePromptDraftChunk(req.params.draftId, chunkIndex, audio)
+    warmTail = warmTail.then(() => transcribeChunk(req.params.draftId, chunkIndex, audio, 'fast', 'warm').then(() => undefined)).catch(err => {
+      console.warn(`[prompt-draft] warm transcription failed ${req.params.draftId}/${chunkIndex}: ${err.message}`)
+    })
+    res.json({ draftId: meta.draftId, chunkIndex, acked: true, receivedChunkIndexes: meta.receivedChunkIndexes, chunkBytes: meta.chunkBytes[String(chunkIndex)] ?? audio.length, transcriptPending: true, expiresAt: meta.expiresAt })
+  } catch (err: any) {
+    res.status(err.status ?? (err.message === 'draft not found' ? 404 : 500)).json({ error: err.message })
+  }
+})
+
+async function finalizeRequest(req: any, res: Response): Promise<void> {
+  const abort = new AbortController()
+  res.on('close', () => { if (!res.writableEnded) abort.abort() })
+  try {
+    const mode = routeMode(req)
+    const key = `${req.params.draftId}:${mode}`
+    let job = finalizeJobs.get(key)
+    if (!job) {
+      job = finalizeDraft(req.params.draftId, mode, routeAutoClean(req), abort.signal)
+      finalizeJobs.set(key, job)
+      job.finally(() => finalizeJobs.delete(key)).catch(() => {})
+    }
+    res.json(await job)
+  } catch (err: any) {
+    await sendDraftError(res, req.params.draftId, err)
+  } finally {
+    clearSessionHallucinationState(sessionId(req.params.draftId))
+  }
+}
+
+promptDraftsRouter.post('/prompt-drafts/:draftId/finalize', finalizeRequest)
+promptDraftsRouter.post('/prompt-drafts/:draftId/retry', finalizeRequest)
+promptDraftsRouter.get('/prompt-drafts/:draftId', (req, res) => {
+  try {
+    const meta = loadPromptDraftMeta(req.params.draftId)
+    if (!meta) return res.status(404).json({ error: 'draft not found' })
+    res.json({ ...meta, missingChunks: getMissingChunkIndexes(meta) })
+  } catch (err: any) {
+    res.status(500).json({ error: err.message })
+  }
+})