@gotcos/glasses-server 6.15.2 → 6.15.5

package/server/lib/whisper-local.ts

@@ -6,10 +6,10 @@
 //   2. whisper-cli (spawned per request, model loaded from disk) → ~500-700ms
 //   3. OpenAI API (cloud, handled by transcribe.ts) → ~1000-3000ms
 
-import { spawn, execFileSync } from 'node:child_process'
+import { spawn, execFile } from 'node:child_process'
 import type { ChildProcess } from 'node:child_process'
 import { writeFileSync, unlinkSync, existsSync, readFileSync } from 'node:fs'
-import { join } from 'node:path'
+import { basename, join } from 'node:path'
 import { homedir } from 'node:os'
 import crypto from 'node:crypto'
 import { getVocabulary, getOwnerName } from './profile.js'
@@ -137,6 +137,10 @@ function getWhisperPrompt(): string {
 // whisper-server runs on this port (started at server boot or by LaunchAgent)
 const WHISPER_SERVER_PORT = 8178
 const WHISPER_SERVER_URL = `http://127.0.0.1:${WHISPER_SERVER_PORT}`
+const PROCESS_PROBE_TIMEOUT_MS = 2_000
+const PROCESS_PROBE_MAX_BUFFER = 1024 * 1024
+const PS_BIN = '/bin/ps'
+const LSOF_BIN = existsSync('/usr/sbin/lsof') ? '/usr/sbin/lsof' : 'lsof'
 
 // Track which backends are available
 let cliAvailable = false
@@ -153,6 +157,10 @@ let serverStarting = false            // Initial model load is not a circuit fai
 let serverStartPromise: Promise<void> | null = null
 let serverRestartPromise: Promise<WhisperRestartResult> | null = null
 let serverHealthProbe: Promise<boolean> | null = null
+type WhisperStartupState = 'not_started' | 'preflight' | 'loading' | 'ready' | 'unavailable' | 'failed' | 'stopped'
+let serverStartupState: WhisperStartupState = 'not_started'
+let serverLastAttemptAt: string | null = null
+let serverLastError: string | null = null
 
 interface ProcessEntry {
   pid: number
@@ -167,10 +175,34 @@ export interface WhisperRestartResult {
 
 const sleep = (ms: number): Promise<void> => new Promise(resolve => setTimeout(resolve, ms))
 
-function listProcesses(): ProcessEntry[] {
+function boundedError(value: unknown): string {
+  const message = value instanceof Error ? value.message : String(value)
+  return message.replace(/[\r\n\t]+/g, ' ').slice(0, 240)
+}
+
+function runProcessProbe(file: string, args: string[]): Promise<string> {
+  return new Promise((resolve, reject) => {
+    execFile(file, args, {
+      encoding: 'utf8',
+      timeout: PROCESS_PROBE_TIMEOUT_MS,
+      maxBuffer: PROCESS_PROBE_MAX_BUFFER,
+      killSignal: 'SIGKILL',
+    }, (error, stdout) => {
+      if (error) reject(error)
+      else resolve(String(stdout))
+    })
+  })
+}
+
+async function listProcesses(): Promise<ProcessEntry[]> {
   // `command=` includes arguments, which lets us distinguish this COS-owned
   // port/model signature from unrelated whisper-server instances.
-  const output = execFileSync('ps', ['-axww', '-o', 'pid=,ppid=,command='], { encoding: 'utf8' })
+  let output: string
+  try {
+    output = await runProcessProbe(PS_BIN, ['-axww', '-o', 'pid=,ppid=,command='])
+  } catch (error) {
+    throw new Error(`unable to inspect process table: ${boundedError(error)}`)
+  }
   return output.split('\n').flatMap(line => {
     const match = line.match(/^\s*(\d+)\s+(\d+)\s+(.+?)\s*$/)
     if (!match) return []
@@ -178,24 +210,25 @@ function listProcesses(): ProcessEntry[] {
   })
 }
 
-function listeningPids(): number[] {
+async function listeningPids(): Promise<number[]> {
   try {
-    const output = execFileSync(
-      'lsof',
+    const output = await runProcessProbe(
+      LSOF_BIN,
       ['-nP', `-iTCP:${WHISPER_SERVER_PORT}`, '-sTCP:LISTEN', '-t'],
-      { encoding: 'utf8' },
     )
     return output.split(/\s+/).map(Number).filter(pid => Number.isInteger(pid) && pid > 0)
   } catch (err: any) {
     // lsof uses exit 1 for "no matches". Anything else means we could not
     // prove the port state, so startup must fail closed.
-    if (err?.status === 1) return []
-    throw new Error(`unable to inspect whisper-server port ${WHISPER_SERVER_PORT}: ${err?.message ?? err}`)
+    if (err?.code === 1 || err?.status === 1) return []
+    throw new Error(`unable to inspect whisper-server port ${WHISPER_SERVER_PORT}: ${boundedError(err)}`)
   }
 }
 
 function isCosWhisperServerCommand(command: string): boolean {
-  const executable = /(?:^|\s)(?:\S*\/)?whisper-server(?:\s|$)/.test(command)
+  const firstToken = command.trim().match(/^(?:"([^"]+)"|'([^']+)'|(\S+))/)
+  const executablePath = firstToken?.[1] ?? firstToken?.[2] ?? firstToken?.[3] ?? ''
+  const executable = basename(executablePath) === 'whisper-server'
   const configuredPort = new RegExp(`(?:^|\\s)--port(?:=|\\s+)${WHISPER_SERVER_PORT}(?:\\s|$)`).test(command)
   return executable && configuredPort && command.includes(MODEL_PATH)
 }
@@ -249,7 +282,7 @@ async function killAndReapWhisperProcesses(): Promise<void> {
   serverAvailable = false
 
   for (let round = 0; round < 3; round++) {
-    const processes = listProcesses()
+    const processes = await listProcesses()
     const ownedPids = [...ownedServerChildren]
       .map(child => child.pid)
       .filter((pid): pid is number => typeof pid === 'number')
@@ -288,7 +321,7 @@ async function killAndReapWhisperProcesses(): Promise<void> {
     await sleep(50)
   }
 
-  const remaining = listProcesses().filter(entry => isCosWhisperServerCommand(entry.command))
+  const remaining = (await listProcesses()).filter(entry => isCosWhisperServerCommand(entry.command))
   if (remaining.length > 0) {
     throw new Error(`stale whisper-server process(es) remain: ${remaining.map(entry => entry.pid).join(', ')}`)
   }
@@ -298,11 +331,11 @@ async function killAndReapWhisperProcesses(): Promise<void> {
 
 async function proveWhisperPortClear(): Promise<void> {
   for (let attempt = 0; attempt < 20; attempt++) {
-    const pids = listeningPids()
+    const pids = await listeningPids()
     if (pids.length === 0) return
     if (attempt < 19) await sleep(250)
   }
-  const pids = listeningPids()
+  const pids = await listeningPids()
   throw new Error(
     `whisper-server port ${WHISPER_SERVER_PORT} remains occupied${pids.length ? ` by PID(s) ${pids.join(', ')}` : ''}`,
   )
@@ -334,10 +367,17 @@ export async function startWhisperServer(): Promise<void> {
   if (serverAvailable && serverProcess) return
 
   serverStarting = true
+  serverStartupState = 'preflight'
+  serverLastAttemptAt = new Date().toISOString()
+  serverLastError = null
   const operation = startWhisperServerAttempt()
   serverStartPromise = operation
   try {
     await operation
+  } catch (error) {
+    serverStartupState = 'failed'
+    serverLastError = boundedError(error)
+    throw error
   } finally {
     if (serverStartPromise === operation) serverStartPromise = null
     serverStarting = false
@@ -346,6 +386,8 @@ export async function startWhisperServer(): Promise<void> {
 
 async function startWhisperServerAttempt(preflightCompleted = false): Promise<void> {
   if (!existsSync(WHISPER_SERVER) || !existsSync(MODEL_PATH)) {
+    serverStartupState = 'unavailable'
+    serverLastError = 'whisper-server or model not found'
     console.log('[whisper-local] whisper-server or model not found — using CLI fallback')
     return
   }
@@ -353,9 +395,12 @@ async function startWhisperServerAttempt(preflightCompleted = false): Promise<vo
   // The API process is the sole Whisper owner. Never adopt an untracked daemon:
   // reap stale trees, then prove the fixed local port is free before spawning.
   if (!preflightCompleted) {
+    console.log('[whisper-local] preflight: inspecting owned processes and port 8178')
+    serverStartupState = 'preflight'
     await killAndReapWhisperProcesses()
     await proveWhisperPortClear()
   }
+  serverStartupState = 'loading'
 
   // Assemble startup args. VAD only attaches if the ggml model is actually on
   // disk — missing-file is logged, not fatal (server still boots without VAD).
@@ -402,6 +447,8 @@ async function startWhisperServerAttempt(preflightCompleted = false): Promise<vo
     if (serverProcess !== child) return
     serverAvailable = false
     serverProcess = null
+    serverStartupState = 'failed'
+    serverLastError = `whisper-server exited${code == null ? '' : ` with code ${code}`}`
     if (code !== null && code !== 0) {
       console.warn(`[whisper-local] whisper-server exited with code ${code}`)
     }
@@ -422,6 +469,8 @@ async function startWhisperServerAttempt(preflightCompleted = false): Promise<vo
       const res = await fetch(`${WHISPER_SERVER_URL}/health`, { signal: AbortSignal.timeout(1000) })
       if (res.ok) {
         serverAvailable = true
+        serverStartupState = 'ready'
+        serverLastError = null
         const loadTime = ((Date.now() - startTime) / 1000).toFixed(1)
         console.log(`[whisper-local] whisper-server ready on port ${WHISPER_SERVER_PORT} (loaded in ${loadTime}s)`)
         return
@@ -444,6 +493,8 @@ async function startWhisperServerAttempt(preflightCompleted = false): Promise<vo
   console.error(`[whisper-local] ${failure} — reaping child and keeping local backend unavailable`)
   await killAndReapWhisperProcesses()
   await proveWhisperPortClear()
+  serverStartupState = 'failed'
+  serverLastError = failure
   throw new Error(failure)
 }
 
@@ -461,6 +512,7 @@ export function stopWhisperServer(): void {
     try { proc.kill('SIGKILL') } catch { /* already exited */ }
   }
   ownedHqChildren.clear()
+  serverStartupState = 'stopped'
 }
 
 export function isWhisperLocalAvailable(): boolean {
@@ -480,17 +532,25 @@ export function getWhisperBackend(): 'server' | 'cli' | 'none' {
 /** Detailed health status for diagnostics (/api/health) */
 export function getWhisperHealth(): {
   server: boolean
+  serverConfigured: boolean
   cli: boolean
   consecutiveFailures: number
   restarting: boolean
   circuitOpen: boolean
+  startupState: WhisperStartupState
+  lastAttemptAt: string | null
+  lastError: string | null
 } {
   return {
     server: serverAvailable,
+    serverConfigured: existsSync(WHISPER_SERVER) && existsSync(MODEL_PATH),
     cli: cliAvailable,
     consecutiveFailures: serverConsecutiveFailures,
     restarting: serverRestarting || serverStarting,
     circuitOpen: serverConsecutiveFailures >= SERVER_FAILURE_THRESHOLD,
+    startupState: serverStartupState,
+    lastAttemptAt: serverLastAttemptAt,
+    lastError: serverLastError,
   }
 }
 
@@ -604,14 +664,22 @@ export async function transcribeHighQuality(
 
     const text = await new Promise<string>((resolve, reject) => {
       const isolateBatchFromLiveMetal = opts.priority === 'batch'
+      // Interactive HQ: narrower beam (default 2) for latency. Meeting batch keeps 5.
+      // Override: COS_HQ_BEAM_INTERACTIVE=N
+      const interactiveBeamRaw = Number.parseInt(process.env.COS_HQ_BEAM_INTERACTIVE || '2', 10)
+      const interactiveBeam = Number.isFinite(interactiveBeamRaw) && interactiveBeamRaw >= 1
+        ? Math.min(interactiveBeamRaw, 5)
+        : 2
+      const beam = isolateBatchFromLiveMetal ? 5 : interactiveBeam
+      const bestOf = beam
       const args = [
         '-m', modelPath,
         '-f', tmpWav,
         '-t', isolateBatchFromLiveMetal ? '8' : '16',
         '-l', 'en',
         ...(isolateBatchFromLiveMetal ? ['-ng'] : ['-fa']),
-        '-bs', '5',           // Beam search width 5 (default disabled)
-        '-bo', '5',           // Best-of-5 candidates (default 2)
+        '-bs', String(beam),
+        '-bo', String(bestOf),
         '--no-timestamps',
         '-np',
         '--prompt', buildPrompt(context),
@@ -966,6 +1034,9 @@ export async function restartWhisperServer(): Promise<WhisperRestartResult> {
   if (serverRestartPromise) return serverRestartPromise
 
   serverRestarting = true
+  serverStartupState = 'preflight'
+  serverLastAttemptAt = new Date().toISOString()
+  serverLastError = null
   const priorStart = serverStartPromise
   const operation = (async (): Promise<WhisperRestartResult> => {
     try {
@@ -984,6 +1055,8 @@ export async function restartWhisperServer(): Promise<WhisperRestartResult> {
         throw new Error('whisper-server did not become healthy')
       }
       serverConsecutiveFailures = 0
+      serverStartupState = 'ready'
+      serverLastError = null
       console.log('[whisper-local] Server restarted successfully — circuit breaker CLOSED')
       return { status: 'recovered' }
     } catch (err: any) {
@@ -992,6 +1065,8 @@ export async function restartWhisperServer(): Promise<WhisperRestartResult> {
       // breaker cycle, and the next three failed calls may request one new cycle.
       serverConsecutiveFailures = 0
       const message = err?.message ?? String(err)
+      serverStartupState = 'failed'
+      serverLastError = boundedError(message)
       console.error(`[whisper-local] Server restart error: ${message} — will retry after next 3 failures`)
       return { status: 'failed', error: message }
     }

package/server/routes/health.ts

@@ -180,6 +180,23 @@ healthRouter.get('/health', async (_req, res) => {
   // Whisper-server health + cloud budget — exposed so glasses + dashboards can
   // see whether we're at risk of falling to cloud and how much budget remains.
   const whisper_health = getWhisperHealth()
+  const whisperReadiness = !whisper_health.serverConfigured
+    ? 'not_configured'
+    : whisper_health.server
+      ? 'ready'
+      : whisper_health.startupState === 'preflight' || whisper_health.startupState === 'loading'
+        ? 'starting'
+        : 'degraded'
+  const readiness = {
+    // /api/health remains a liveness endpoint and intentionally returns HTTP
+    // 200 while the server can answer. This separate field prevents an HTTP-
+    // green response from hiding a configured local subsystem failure.
+    status: whisperReadiness === 'degraded' ? 'degraded' : 'ready',
+    admissions: maintenance.admissionsOpen ? 'open' : 'maintenance',
+    whisper: whisperReadiness,
+    whisperError: whisper_health.lastError,
+    localTts: tts_local.ready ? 'ready' : 'unavailable',
+  }
   const openai_whisper_budget = getOpenAIWhisperBudgetState()
   const codex_models = getCodexModelCatalogSnapshot()
   res.json({
@@ -190,6 +207,7 @@ healthRouter.get('/health', async (_req, res) => {
     generation_id: getServerGenerationId(),
     features,
     voice,
+    readiness,
     whisper_health,
     openai_whisper_budget,
     tts_local,

package/server/routes/openai-compat.ts

@@ -295,6 +295,21 @@ openaiCompatRouter.post('/v1/chat/completions', async (req, res) => {
   void inflightPromise.catch(() => { /* duplicate waiters observe the original rejection */ })
   inflightQueries.set(dedupKey, { promise: inflightPromise, timestamp: Date.now() })
 
+  // Register disconnect cancellation before the provider starts. G2 can abort
+  // its first fetch while Claude/Codex continues running; without this signal
+  // the provider and its maintenance lease can strand a Control restart for
+  // the full model timeout. The lease is released only after the bridge reaches
+  // its terminal callback/catch, never merely because the socket disappeared.
+  const providerAbort = new AbortController()
+  let responseFinished = false
+  let clientDisconnected = false
+  res.once('finish', () => { responseFinished = true })
+  res.once('close', () => {
+    if (responseFinished) return
+    clientDisconnected = true
+    providerAbort.abort(new Error('G2 client disconnected'))
+  })
+
   // ── Streaming response (SSE) ──
   if (stream) {
     res.writeHead(200, {
@@ -326,7 +341,7 @@ openaiCompatRouter.post('/v1/chat/completions', async (req, res) => {
     try {
       const returnedSid = await callModelStreaming(query, currentSessionId, {
         onChunk: (text) => {
-          if (!done) {
+          if (!done && !clientDisconnected) {
             if (!firstChunkLogged) {
               firstChunkLogged = true
               actualTtfbMs = Date.now() - requestReceivedAt
@@ -360,16 +375,18 @@ openaiCompatRouter.post('/v1/chat/completions', async (req, res) => {
               stream_requested: true,
               })
               // Final chunk with finish_reason
-              const finalChunk = {
-              id: completionId,
-              object: 'chat.completion.chunk',
-              created: timestamp,
-              model: responseModel,
-              choices: [{ index: 0, delta: {}, finish_reason: 'stop' }],
+              if (!clientDisconnected) {
+                const finalChunk = {
+                  id: completionId,
+                  object: 'chat.completion.chunk',
+                  created: timestamp,
+                  model: responseModel,
+                  choices: [{ index: 0, delta: {}, finish_reason: 'stop' }],
+                }
+                res.write(`data: ${JSON.stringify(finalChunk)}\n\n`)
+                res.write('data: [DONE]\n\n')
+                res.end()
               }
-              res.write(`data: ${JSON.stringify(finalChunk)}\n\n`)
-              res.write('data: [DONE]\n\n')
-              res.end()
             }
           } finally {
             maintenanceLease.release()
@@ -381,29 +398,34 @@ openaiCompatRouter.post('/v1/chat/completions', async (req, res) => {
               done = true
               rejectInflight!(new Error(error))
               inflightQueries.delete(dedupKey)
-              const errChunk = {
-              id: completionId,
-              object: 'chat.completion.chunk',
-              created: timestamp,
-              model: responseModel,
-              choices: [{ index: 0, delta: { content: `Error: ${error}` }, finish_reason: 'stop' }],
+              if (!clientDisconnected) {
+                const errChunk = {
+                  id: completionId,
+                  object: 'chat.completion.chunk',
+                  created: timestamp,
+                  model: responseModel,
+                  choices: [{ index: 0, delta: { content: `Error: ${error}` }, finish_reason: 'stop' }],
+                }
+                res.write(`data: ${JSON.stringify(errChunk)}\n\n`)
+                res.write('data: [DONE]\n\n')
+                res.end()
               }
-              res.write(`data: ${JSON.stringify(errChunk)}\n\n`)
-              res.write('data: [DONE]\n\n')
-              res.end()
             }
           } finally {
             maintenanceLease.release()
           }
         },
         onToolStatus: (status) => {
-          if (!done) {
+          if (!done && !clientDisconnected) {
             // SSE comment — invisible to JSON parsers but keeps connection alive
             res.write(`: ${status}\n\n`)
           }
         },
         onStart: () => {},
-      }, resolvedModel, undefined, undefined, undefined, { lightweight: true })
+      }, resolvedModel, undefined, undefined, undefined, {
+        lightweight: true,
+        abortSignal: providerAbort.signal,
+      })
       // Persist session ID for multi-turn context on subsequent G2 queries
       g2SessionId = returnedSid
     } catch (err: any) {
@@ -412,13 +434,13 @@ openaiCompatRouter.post('/v1/chat/completions', async (req, res) => {
         done = true
         rejectInflight!(err)
         inflightQueries.delete(dedupKey)
-        res.write(`data: ${JSON.stringify({ error: { message: err.message } })}\n\n`)
-        res.write('data: [DONE]\n\n')
-        res.end()
+        if (!clientDisconnected) {
+          res.write(`data: ${JSON.stringify({ error: { message: err.message } })}\n\n`)
+          res.write('data: [DONE]\n\n')
+          res.end()
+        }
       }
     }
-
-    req.on('close', () => { done = true })
     return
   }
 
@@ -479,11 +501,15 @@ openaiCompatRouter.post('/v1/chat/completions', async (req, res) => {
         },
         onToolStatus: () => {},
         onStart: () => {},
-      }, resolvedModel, undefined, undefined, undefined, { lightweight: true })
+      }, resolvedModel, undefined, undefined, undefined, {
+        lightweight: true,
+        abortSignal: providerAbort.signal,
+      })
         .then(sid => { g2SessionId = sid })
         .catch(fail)
     })
 
+    if (clientDisconnected) return
     res.json({
       id: completionId,
       object: 'chat.completion',
@@ -497,6 +523,7 @@ openaiCompatRouter.post('/v1/chat/completions', async (req, res) => {
       usage: { prompt_tokens: 0, completion_tokens: 0, total_tokens: 0 },
     })
   } catch (err: any) {
+    if (clientDisconnected) return
     res.status(500).json({
       error: { message: err.message, type: 'server_error' },
     })

package/server/routes/prompt-drafts.ts

@@ -52,9 +52,18 @@ export const promptDraftsRouter = Router()
 const MAX_CHUNK_BYTES = 25 * 1024 * 1024
 const MAX_DRAFT_BYTES = 256 * 1024 * 1024
 const MAX_CHUNKS = 600
+/** Purpose-scoped keys (legacy). Prefer modeQualityJobs for HQ warm↔finalize dedupe. */
 const chunkTranscriptJobs = new Map<string, Promise<string>>()
+/** Shared decode per draft/chunk/mode/hash — warm:hq and final:hq await the same promise. */
+const modeQualityJobs = new Map<string, Promise<string>>()
 const finalizeJobs = new Map<string, Promise<any>>()
 let warmTail: Promise<void> = Promise.resolve()
+let hqWarmTail: Promise<void> = Promise.resolve()
+
+/** Speculative HQ warm while speaking. Set COS_HQ_SPECULATIVE_WARM=0 to restore Fast-only warm. */
+function speculativeHqWarmEnabled(): boolean {
+  return !['0', 'false', 'off'].includes((process.env.COS_HQ_SPECULATIVE_WARM ?? '1').toLowerCase())
+}
 
 const autoCleanBreaker = createBreaker({ label: 'dictation-autoclean' })
 const autoCleanCountFile = () => process.env.COS_DICTATION_AUTOCLEAN_COUNT_FILE || dataPath('.dictation_autoclean_count.json')
@@ -164,14 +173,49 @@ async function sendDraftError(res: Response, draftId: string, err: any): Promise
   res.status(err.status ?? 500).json({ error: err.message })
 }
 
+function modeQualityKey(draftId: string, chunkIndex: number, mode: 'hq' | 'fast', hash: string): string {
+  return `${draftId}:${chunkIndex}:${mode}:${hash}`
+}
+
 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)
+  const purposeKey = `${draftId}:${chunkIndex}:${purpose}:${mode}:${hash}`
+  const sharedKey = modeQualityKey(draftId, chunkIndex, mode, hash)
+
+  // HQ warm and HQ finalize must share one decode (plan step 8a).
+  const existingShared = modeQualityJobs.get(sharedKey)
+  if (existingShared) {
+    try {
+      const text = await existingShared
+      if (purpose === 'final' && text) {
+        const current = loadPromptDraftMeta(draftId)
+        const warm = current?.warmTranscripts?.[String(chunkIndex)]
+        const cachedFinal = current?.finalTranscripts?.[String(chunkIndex)]
+        if (!cachedFinal || cachedFinal.hash !== hash) {
+          await markPromptDraftChunkTranscript(draftId, chunkIndex, {
+            text,
+            hash,
+            requestedMode: warm?.requestedMode ?? mode,
+            actualQuality: warm?.actualQuality ?? (mode === 'hq' ? 'hq' : 'fast'),
+            backend: warm?.backend ?? 'shared-inflight',
+            degraded: warm?.degraded ?? false,
+          }, 'final')
+        }
+      }
+      return text
+    } catch {
+      // Shared warm failed under local-only; fall through so finalize can retry with automatic.
+    }
+  }
+
+  const existing = chunkTranscriptJobs.get(purposeKey)
   if (existing) return existing
+
   const job = (async () => {
     try {
-      const result = await transcribeAudioBuffer(audio, { mode, policy: purpose === 'warm' ? 'local-only' : 'automatic' })
+      // Speculative warm is always local-only. Finalize may use automatic cloud fallback.
+      const policy = purpose === 'warm' ? 'local-only' as const : 'automatic' as const
+      const result = await transcribeAudioBuffer(audio, { mode, policy })
       if (!isCurrentChunk(draftId, chunkIndex, audio)) return ''
       const text = sanitizeTranscript(draftId, result.text)
       const record: PromptDraftTranscriptRecord = {
@@ -179,7 +223,7 @@ async function transcribeChunk(draftId: string, chunkIndex: number, audio: Buffe
         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`)
+      console.log(`[prompt-draft] chunk ${draftId}/${chunkIndex}: ${result.elapsedMs.toFixed(1)}ms | ${result.backend} | ${purpose}/${mode} | ${text.length} chars`)
       return text
     } catch (err) {
       if (err instanceof NoSpeechDetectedError) {
@@ -190,10 +234,12 @@ async function transcribeChunk(draftId: string, chunkIndex: number, audio: Buffe
       }
       throw err
     } finally {
-      chunkTranscriptJobs.delete(key)
+      chunkTranscriptJobs.delete(purposeKey)
+      modeQualityJobs.delete(sharedKey)
     }
   })()
-  chunkTranscriptJobs.set(key, job)
+  chunkTranscriptJobs.set(purposeKey, job)
+  modeQualityJobs.set(sharedKey, job)
   return job
 }
 
@@ -203,9 +249,17 @@ async function finalizeDraft(draftId: string, mode: 'hq' | 'fast', autoClean: Au
   const texts: string[] = []
   for (const chunk of readPromptDraftChunks(draftId)) {
     try {
+      const hash = audioHash(chunk.audioBuffer)
+      // Await in-flight HQ warm before deciding cache miss (plan step 8b belt).
+      if (mode === 'hq') {
+        const inflight = modeQualityJobs.get(modeQualityKey(draftId, chunk.chunkIndex, 'hq', hash))
+        if (inflight) {
+          try { await inflight } catch { /* finalize may retry with automatic below */ }
+        }
+      }
       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 reusable = Boolean(cached && cached.hash === hash && (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())
@@ -265,10 +319,13 @@ promptDraftsRouter.post('/prompt-drafts/:draftId/chunks', async (req, res) => {
     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)
+    const requestedMode = routeMode(req)
     const warmLease = acquireMaintenanceWork('prompt_draft_warm', {
       allowDuringDrain: true,
       phase: 'queued',
     })
+    // Fast warm feeds the live HUD. Speculative HQ (when Settings HQ / default)
+    // overwrites warmTranscripts with actualQuality=hq for near-instant finalize.
     warmTail = warmTail.then(async () => {
       warmLease.setPhase('active')
       const text = await transcribeChunk(req.params.draftId, chunkIndex, audio, 'fast', 'warm')
@@ -283,6 +340,21 @@ promptDraftsRouter.post('/prompt-drafts/:draftId/chunks', async (req, res) => {
     }).catch(err => {
       console.warn(`[prompt-draft] warm transcription failed ${req.params.draftId}/${chunkIndex}: ${err.message}`)
     }).finally(() => warmLease.release())
+
+    if (requestedMode === 'hq' && speculativeHqWarmEnabled()) {
+      const hqLease = acquireMaintenanceWork('prompt_draft_warm', {
+        allowDuringDrain: true,
+        phase: 'queued',
+      })
+      hqWarmTail = hqWarmTail.then(async () => {
+        hqLease.setPhase('active')
+        // Cache only — never emitDisplay HQ (avoids HUD flicker). local-only via purpose=warm.
+        await transcribeChunk(req.params.draftId, chunkIndex, audio, 'hq', 'warm')
+      }).catch(err => {
+        console.warn(`[prompt-draft] speculative HQ warm failed ${req.params.draftId}/${chunkIndex}: ${err.message}`)
+      }).finally(() => hqLease.release())
+    }
+
     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) {
     if (err instanceof MaintenanceLifecycleError) {

package/server/routes/provider-proof.ts

@@ -1,5 +1,11 @@
 import { Router } from 'express'
 import { runProviderProof, type ProofProvider } from '../lib/provider-proof.js'
+import {
+  acquireMaintenanceWork,
+  maintenanceErrorPayload,
+  maintenanceOperationCredentialsValid,
+  MaintenanceLifecycleError,
+} from '../lib/maintenance-lifecycle.js'
 
 export const providerProofRouter = Router()
 
@@ -14,6 +20,38 @@ providerProofRouter.post('/diagnostics/provider-proof', async (req, res) => {
   if (provider !== 'claude' && provider !== 'codex') {
     return res.status(400).json({ error: 'provider must be claude or codex' })
   }
-  const result = await runProviderProof(provider as ProofProvider)
-  return res.status(result.ok ? 200 : 503).json(result)
+  const controllerProof = maintenanceOperationCredentialsValid({
+    leaseId: typeof req.headers['x-cos-maintenance-lease'] === 'string'
+      ? req.headers['x-cos-maintenance-lease'] : undefined,
+    operationId: typeof req.headers['x-cos-maintenance-operation'] === 'string'
+      ? req.headers['x-cos-maintenance-operation'] : undefined,
+    nonce: typeof req.headers['x-cos-maintenance-nonce'] === 'string'
+      ? req.headers['x-cos-maintenance-nonce'] : undefined,
+  })
+  let lease
+  try {
+    lease = acquireMaintenanceWork('api_mutation', { allowDuringDrain: controllerProof })
+  } catch (error) {
+    if (error instanceof MaintenanceLifecycleError) {
+      if (error.retryAfterSeconds != null) res.setHeader('Retry-After', String(error.retryAfterSeconds))
+      return res.status(error.status).json(maintenanceErrorPayload(error))
+    }
+    return res.status(500).json({ error: 'maintenance_internal_error', retryable: false })
+  }
+
+  const abort = new AbortController()
+  let responseFinished = false
+  const cancel = () => { if (!responseFinished) abort.abort(new Error('Control proof client disconnected')) }
+  req.once('aborted', cancel)
+  res.once('finish', () => { responseFinished = true })
+  res.once('close', cancel)
+  try {
+    const result = await runProviderProof(provider as ProofProvider, abort.signal)
+    if (abort.signal.aborted) return
+    return res.status(result.ok ? 200 : 503).json(result)
+  } finally {
+    req.removeListener('aborted', cancel)
+    res.removeListener('close', cancel)
+    lease.release()
+  }
 })