@gotcos/glasses-server 6.11.0 → 6.12.0

package/.env.example

@@ -58,8 +58,10 @@ BIND_HOST=0.0.0.0
 
 # ── VOICE (optional) ────────────────────────────────────────────────────
 # Local transcription is FREE via whisper.cpp (brew install whisper-cpp; the
-# model auto-downloads on first run). If whisper.cpp is absent, voice falls
-# back to the OpenAI API (~$0.006/min), which needs this key.
+# model auto-downloads on first run). Voice is local-only by default. Merely
+# configuring a key never uploads audio. To allow OpenAI Whisper only after a
+# local failure, set BOTH the exact opt-in and a key:
+# COS_OPENAI_WHISPER_FALLBACK=1
 # OPENAI_API_KEY=sk-...
 
 # ── FULL COS PIPELINE (optional — leave unset for standalone) ────────────

package/CHANGELOG.md

@@ -1,5 +1,30 @@
 # Changelog
 
+## 6.12.0
+
+Local-first transcription policy and capability-safe recovery diagnostics for
+COS Glasses build 210+.
+
+- **Local means local.** Prompt, one-shot, and meeting transcription now remain
+  on local Whisper by default. Finding an OpenAI key is not permission to upload
+  audio. Cloud Whisper is reachable only when the exact
+  `COS_OPENAI_WHISPER_FALLBACK=1` opt-in and a resolved key are both present.
+- **Every cloud chokepoint is fenced.** Both one-shot/prompt finalization and
+  continuous meeting transcription recheck the policy immediately before any
+  OpenAI request, preventing a future call-site regression from bypassing the
+  top-level selection logic.
+- **Failure stays recoverable.** A local ASR outage returns a typed retryable
+  `503` instead of silently switching providers. Durable prompt chunks and raw
+  meeting audio remain available for retry; meeting receipt and batch-audio
+  retention behavior is unchanged.
+- **Clients can tell policy from health.** `/api/health` and `/api/models`
+  publish additive `capabilities.transcription` fields. Public installs also
+  advertise every privileged recovery control as unsupported, allowing newer
+  phone Recovery Centers to hide controls instead of reporting false outages.
+- **Backward compatible.** Existing routes and response fields remain in place.
+  Older apps keep their current query, prompt, meeting, image, and display
+  paths; cloud fallback remains available to operators who explicitly enable it.
+
 ## 6.11.0
 
 Local-first meeting recovery for COS Glasses build 209+.

package/README.md

@@ -27,7 +27,7 @@ without silently losing completed replies.
 - **Claude Code CLI** (Opus/Fable/Sonnet) — https://claude.ai/download, then `claude login`
   _or_ **Codex CLI** (GPT Frontier/Balanced) — https://developers.openai.com/codex/, then `codex login`
 - **Even G2 glasses** + the **COS Glasses** app from the Even Hub
-- _Optional:_ `brew install whisper-cpp` for free local voice (otherwise OpenAI API)
+- `brew install whisper-cpp` for free local voice (the launcher can download the model)
 - _Optional:_ `brew install ffmpeg` for phone/output image attachments (text chat remains available without it)
 - _Optional:_ **Tailscale** so your phone reaches your Mac from anywhere
 
@@ -76,7 +76,10 @@ The built-in IP allowlist blocks public-internet traffic regardless.
   locally through a network interruption. Reconnecting reconciles the exact
   chunks already stored by the Mac, uploads only missing audio, and finalizes
   through an idempotent save receipt without duplicating the meeting.
-- Local whisper.cpp transcription (free) with OpenAI fallback (optional)
+- Local whisper.cpp transcription (free and local-only by default). OpenAI
+  Whisper fallback is optional and requires both the exact
+  `COS_OPENAI_WHISPER_FALLBACK=1` opt-in and a configured key; a key alone never
+  uploads audio.
 - Tasks / calendar / people context **if** you run the
   [COS Starter Kit](https://www.gotcos.com) (`COS_SCRIPTS_DIR`); otherwise it is
   glasses + AI only
@@ -85,7 +88,8 @@ The built-in IP allowlist blocks public-internet traffic regardless.
 
 Config lives at `~/.cos-glasses/.env` (created on first run). Every key is
 optional except an installed CLI. Highlights: `BIND_HOST`, `PORT`,
-`COS_API_TOKEN` (auto if unset), `OPENAI_API_KEY` (cloud voice fallback),
+`COS_API_TOKEN` (auto if unset), `COS_OPENAI_WHISPER_FALLBACK=1` plus
+`OPENAI_API_KEY` (explicit cloud voice fallback),
 `COS_SCRIPTS_DIR` (full pipeline), `COS_DURABLE_QUERY_JOBS=1` (build 204+
 server-owned query recovery), and `COS_MEDIA_ROOT` (optional image-store
 location; default `~/.cos-glasses/data/media`). Your name + transcription vocabulary live in
@@ -105,7 +109,13 @@ BIND_HOST=0.0.0.0 npm run start:server
 - *Phone can't connect* — check `BIND_HOST=0.0.0.0`, the same Tailscale account on both devices, and the correct `100.x` IP + token.
 - *Safari connects but the app does not* — confirm `npx @gotcos/glasses-server@latest` is 6.6.0+, then use the app's server reconnect/edit control to verify the current URL and token. Do not run a second source or `npx` server alongside it.
 - *AI queries fail* — run `claude --version` / `codex --version`, then `claude login` / `codex login`.
-- *Voice getting billed?* — install `whisper-cpp` for free local transcription.
+- *Voice getting billed?* — voice is local-only by default in 6.12.0+. Confirm
+  `/api/health` reports `capabilities.transcription.mode: "local-only"`. Remove
+  `COS_OPENAI_WHISPER_FALLBACK` (or set it to `0`) to disable an earlier opt-in.
+- *Local voice unavailable?* — install `whisper-cpp`, restart the server, and
+  confirm `/api/health` reports `features.whisper: true`. A typed retryable 503
+  keeps compatible prompt/meeting audio available for retry instead of silently
+  sending it to OpenAI.
 - *Photos unavailable?* — install `ffmpeg`, restart the server, and confirm `/api/health` reports `features.mediaProcessingReady: true`.
 - *Prompt recovery unavailable?* — update with `npx @gotcos/glasses-server@latest`, then confirm `/api/health` reports `features.promptRecovery: true`.
 - *Durable query recovery unavailable?* — build 204+ requires server 6.10.0+ and

package/bin/cli.cjs

@@ -133,7 +133,8 @@ if (!existsSync(PROFILE_FILE) && existsSync(PROFILE_EXAMPLE)) {
 }
 if (!process.env.COS_PROFILE_PATH) process.env.COS_PROFILE_PATH = PROFILE_FILE
 
-// Step 5: local Whisper detection + model download (free voice; OpenAI fallback otherwise)
+// Step 5: local Whisper detection + model download. Voice stays local-only by
+// default; cloud fallback requires an explicit flag plus a configured key.
 const WHISPER_KNOWN_PATHS = ['/opt/homebrew/bin/whisper-cli', '/usr/local/bin/whisper-cli']
 const WHISPER_MODEL_DIR = join(homedir(), '.local/share/whisper-models')
 const WHISPER_MODEL_PATH = join(WHISPER_MODEL_DIR, 'ggml-large-v3-turbo.bin')
@@ -161,10 +162,10 @@ if (whisperCliPath && hasValidModel) {
   if (existsSync(WHISPER_MODEL_PATH)) { try { unlinkSync(WHISPER_MODEL_PATH) } catch {} }
   if (existsSync(WHISPER_MODEL_PARTIAL)) { try { unlinkSync(WHISPER_MODEL_PARTIAL) } catch {} }
   console.log(yellow('  ⚠') + ' whisper.cpp installed but model missing')
-  console.log('    ' + dim('Downloading ggml-large-v3-turbo (~1.5 GB). Ctrl-C to skip (uses OpenAI API instead).'))
+  console.log('    ' + dim('Downloading ggml-large-v3-turbo (~1.5 GB). Ctrl-C to skip (voice remains unavailable by default).'))
   console.log('    ' + dim('Skip permanently: SKIP_WHISPER_DOWNLOAD=1 npx @gotcos/glasses-server'))
   if (process.env.SKIP_WHISPER_DOWNLOAD === '1') {
-    console.log(yellow('  ⚠') + ' SKIP_WHISPER_DOWNLOAD=1 — voice will use OpenAI API')
+    console.log(yellow('  ⚠') + ' SKIP_WHISPER_DOWNLOAD=1 — local voice unavailable')
   } else {
     try {
       mkdirSync(WHISPER_MODEL_DIR, { recursive: true })
@@ -175,14 +176,19 @@ if (whisperCliPath && hasValidModel) {
       console.log(green('  ✓') + ' Model downloaded ' + dim('— voice = local (FREE)'))
     } catch (err) {
       try { unlinkSync(WHISPER_MODEL_PARTIAL) } catch {}
-      console.log(red('  ✗') + ' Model download failed ' + dim('— voice will use OpenAI API'))
+      console.log(red('  ✗') + ' Model download failed ' + dim('— local voice unavailable'))
       console.log('    ' + dim('Error: ' + (err.message || err).toString().slice(0, 120)))
     }
   }
 } else {
-  console.log(yellow('  ⚠') + ' whisper.cpp not installed ' + dim('— voice will use OpenAI API ($0.006/min)'))
+  console.log(yellow('  ⚠') + ' whisper.cpp not installed ' + dim('— local voice unavailable'))
   console.log('    Free local voice: ' + bold('brew install whisper-cpp') + dim('  (no Homebrew? https://brew.sh)'))
 }
+if (process.env.COS_OPENAI_WHISPER_FALLBACK === '1') {
+  console.log(yellow('  ⚠') + ' Explicit OpenAI Whisper fallback requested ' + dim('— activates only if a key resolves; see /api/health'))
+} else {
+  console.log(green('  ✓') + ' Transcription policy: local-only ' + dim('— a key alone never uploads audio'))
+}
 
 // Step 6: image capability — ffmpeg validates, strips metadata, normalizes,
 // and builds the exact 288x144 G2 variant. It is optional so text/voice remain

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gotcos/glasses-server",
-  "version": "6.11.0",
+  "version": "6.12.0",
   "description": "COS Glasses — self-hosted AI heads-up-display server for Even G2 smart glasses, powered by your local Claude Code or Codex CLI",
   "type": "module",
   "bin": {

package/server/lib/transcribe-audio.ts

@@ -21,6 +21,7 @@ import {
   countVocabTerms,
 } from './hallucination-filter.js'
 import { getOpenAIKey, tryGetOpenAIKey } from './openai-key.js'
+import { getTranscriptionPolicySnapshot, isOpenAIWhisperFallbackReady } from './transcription-policy.js'
 
 export { OpenAIWhisperBudgetExhaustedError, estimateAudioSeconds }
 
@@ -61,17 +62,30 @@ export class NoSpeechDetectedError extends Error {
 // ceiling (anything longer is a dictation, not a query — use meetings instead).
 const HQ_MAX_SECONDS = 60
 
+function unavailableAfterLocalFailure(): TranscriptionUnavailableError | null {
+  const fallback = getTranscriptionPolicySnapshot()
+  if (fallback.openaiFallbackReady) return null
+  return fallback.openaiFallbackConfigured
+    ? new TranscriptionUnavailableError('openai_key_missing', 'Local transcription is unavailable and the explicitly configured OpenAI fallback has no key')
+    : new TranscriptionUnavailableError('local_asr_unavailable', 'Local transcription is unavailable; retry after Whisper recovers')
+}
+
 /** Transcribe via OpenAI Whisper API (cloud fallback).
  *  Budget-gated: throws OpenAIWhisperBudgetExhaustedError if today's $5 cap is spent.
  *  Ledger only ticks on SUCCESSFUL responses so retries that never reach the API
  *  aren't double-counted. */
 async function transcribeCloud(audioBuffer: Buffer): Promise<string> {
-  assertOpenAIWhisperBudget()
+  // Defense in depth: every cloud chokepoint rechecks the explicit two-factor
+  // opt-in. A key alone is never authority to upload user audio.
+  if (!isOpenAIWhisperFallbackReady()) {
+    throw unavailableAfterLocalFailure()!
+  }
 
   if (!tryGetOpenAIKey()) {
-    throw new TranscriptionUnavailableError('openai_key_missing', 'OpenAI key missing; local audio is preserved for retry')
+    throw new TranscriptionUnavailableError('openai_key_missing', 'OpenAI key missing; retry after local Whisper recovers')
   }
 
+  assertOpenAIWhisperBudget()
   const key = getOpenAIKey()
   const audioSeconds = estimateAudioSeconds(audioBuffer)
 
@@ -157,10 +171,14 @@ export async function transcribeAudioBuffer(
         backend = `fast-local-${result.backend}`
         actualQuality = 'fast'
       } catch (localErr: any) {
-        if (policy === 'local-only') {
-          throw new TranscriptionUnavailableError('local_asr_unavailable', `Local transcription unavailable; audio is preserved for retry (${localErr.message})`)
+        const unavailable = policy === 'local-only'
+          ? new TranscriptionUnavailableError('local_asr_unavailable', 'Local transcription is unavailable; retry after Whisper recovers')
+          : unavailableAfterLocalFailure()
+        if (unavailable) {
+          console.warn(`[transcribe] Fast local unavailable; preserving audio for retry: ${localErr.message}`)
+          throw unavailable
         }
-        console.warn(`[transcribe] Fast local also failed, falling back to cloud: ${localErr.message}`)
+        console.warn(`[transcribe] Fast local also failed; using explicitly enabled OpenAI fallback: ${localErr.message}`)
         text = await transcribeCloud(audioBuffer)
         backend = 'cloud'
         actualQuality = 'cloud'
@@ -173,17 +191,24 @@ export async function transcribeAudioBuffer(
       backend = `fast-local-${result.backend}`
       actualQuality = 'fast'
     } catch (localErr: any) {
-      if (policy === 'local-only') {
-        throw new TranscriptionUnavailableError('local_asr_unavailable', `Local transcription unavailable; audio is preserved for retry (${localErr.message})`)
+      const unavailable = policy === 'local-only'
+        ? new TranscriptionUnavailableError('local_asr_unavailable', 'Local transcription is unavailable; retry after Whisper recovers')
+        : unavailableAfterLocalFailure()
+      if (unavailable) {
+        console.warn(`[transcribe] Local unavailable; preserving audio for retry: ${localErr.message}`)
+        throw unavailable
       }
-      console.warn(`[transcribe] Local whisper failed (${getWhisperBackend()}), falling back to cloud: ${localErr.message}`)
+      console.warn(`[transcribe] Local whisper failed (${getWhisperBackend()}); using explicitly enabled OpenAI fallback: ${localErr.message}`)
       text = await transcribeCloud(audioBuffer)
       backend = 'cloud'
       actualQuality = 'cloud'
     }
   } else {
-    if (policy === 'local-only') {
-      throw new TranscriptionUnavailableError('local_asr_unavailable', 'Local transcription unavailable; audio is preserved for retry')
+    const unavailable = policy === 'local-only'
+      ? new TranscriptionUnavailableError('local_asr_unavailable', 'Local transcription is unavailable; retry after Whisper recovers')
+      : unavailableAfterLocalFailure()
+    if (unavailable) {
+      throw unavailable
     }
     text = await transcribeCloud(audioBuffer)
     backend = 'cloud'

package/server/lib/transcription-policy.ts

@@ -0,0 +1,29 @@
+import { getKeyStatus } from './openai-key.js'
+
+/**
+ * Cloud transcription is a two-factor opt-in. Merely having an OpenAI key on
+ * the machine must never route voice away from local Whisper.
+ */
+export const OPENAI_WHISPER_FALLBACK_ENV = 'COS_OPENAI_WHISPER_FALLBACK'
+
+export interface TranscriptionPolicySnapshot {
+  mode: 'local-only' | 'local-then-openai'
+  localRequired: true
+  openaiFallbackConfigured: boolean
+  openaiFallbackReady: boolean
+}
+
+export function getTranscriptionPolicySnapshot(): TranscriptionPolicySnapshot {
+  const openaiFallbackConfigured = process.env[OPENAI_WHISPER_FALLBACK_ENV] === '1'
+  const openaiFallbackReady = openaiFallbackConfigured && getKeyStatus().hasKey
+  return {
+    mode: openaiFallbackReady ? 'local-then-openai' : 'local-only',
+    localRequired: true,
+    openaiFallbackConfigured,
+    openaiFallbackReady,
+  }
+}
+
+export function isOpenAIWhisperFallbackReady(): boolean {
+  return getTranscriptionPolicySnapshot().openaiFallbackReady
+}

package/server/lib/whisper-local.ts

@@ -636,7 +636,7 @@ export async function transcribeLocal(audioBuffer: Buffer, context?: string, isQ
   }
 
   if (!serverAvailable && (serverStarting || serverRestarting)) {
-    throw new Error('whisper-server starting — use preserved/cloud fallback')
+    throw new Error('whisper-server starting — preserve audio for retry')
   }
 
   // Try whisper-server first (fastest: ~50-100ms, includes DTW word timestamps)
@@ -690,13 +690,15 @@ export async function transcribeLocal(audioBuffer: Buffer, context?: string, isQ
     restartWhisperServer()
   }
 
-  // Throw so caller uses cloud fallback — CLI is intentionally skipped for real-time
-  throw new Error('whisper-server unavailable — use cloud fallback')
+  // Throw so the caller applies the configured recovery policy. CLI is
+  // intentionally skipped for real-time transcription.
+  throw new Error('whisper-server unavailable — apply configured recovery policy')
 }
 
 /**
  * Auto-restart whisper-server after circuit breaker triggers.
- * Non-blocking — runs in background while callers use cloud fallback.
+ * Non-blocking — runs in background while callers preserve audio or apply the
+ * explicitly configured fallback policy.
  */
 async function restartWhisperServer(): Promise<void> {
   if (serverRestarting) return
@@ -734,7 +736,7 @@ async function restartWhisperServer(): Promise<void> {
       // Without this, the counter stays >= threshold but serverRestarting is false,
       // so every subsequent call would re-trigger restart in a tight loop
       serverConsecutiveFailures = 0
-      console.error('[whisper-local] Server restart failed — reset counter, will retry after next 3 failures. Using cloud fallback.')
+      console.error('[whisper-local] Server restart failed — reset counter, will retry after next 3 failures. Caller recovery policy remains active.')
     }
   } catch (err: any) {
     serverConsecutiveFailures = 0  // Same reset — allow future retry cycle

package/server/routes/health.ts

@@ -19,6 +19,7 @@ import { isMediaProcessingReady } from '../lib/image-safety.js'
 import { G2_LENS_VARIANT_CAPABILITY } from '../lib/media-store.js'
 import { durableQueryJobsCapability } from '../lib/query-job-feature.js'
 import { getQueryJobRuntimeHealth } from '../lib/query-job-runtime.js'
+import { getTranscriptionPolicySnapshot } from '../lib/transcription-policy.js'
 
 export const healthRouter = Router()
 
@@ -140,6 +141,13 @@ healthRouter.get('/health', async (_req, res) => {
   const keyStatus = getKeyStatus()
   const durableJobs = durableQueryJobStatus()
   const localFirstMeetings = localFirstMeetingsCapability(getServerInstanceId())
+  const transcription = getTranscriptionPolicySnapshot()
+  const recovery = {
+    status: false,
+    restartWhisper: false,
+    restartServer: false,
+    managed: false,
+  }
   const features = {
     claude: claudeAvailable,
     codex: codexAvailable,
@@ -154,6 +162,7 @@ healthRouter.get('/health', async (_req, res) => {
     durableQueryJobs: durableJobs.enabled,
     durableQueryJobsProtocol: durableJobs.protocolVersion,
     localFirstMeetings: localFirstMeetings !== null,
+    transcriptionPolicy: transcription.mode,
   }
   const voice = {
     hasKey: keyStatus.hasKey,
@@ -173,7 +182,11 @@ healthRouter.get('/health', async (_req, res) => {
     whisper_health,
     openai_whisper_budget,
     codex_models,
-    capabilities: localFirstMeetings ? { localFirstMeetings } : {},
+    capabilities: {
+      transcription,
+      recovery,
+      ...(localFirstMeetings ? { localFirstMeetings } : {}),
+    },
     // /api/health is intentionally unauthenticated for setup diagnostics.
     // Publish capability only; job counts, retention identities, subscriber
     // counts, and the storage fingerprint remain internal.
@@ -192,6 +205,7 @@ healthRouter.get('/models', async (req, res) => {
   const catalog = await getCodexModelCatalog(req.query.refresh === '1')
   const durableJobs = durableQueryJobStatus()
   const localFirstMeetings = localFirstMeetingsCapability(getServerInstanceId())
+  const transcription = getTranscriptionPolicySnapshot()
   res.json({
     ...catalog,
     serverInstanceId: getServerInstanceId(),
@@ -200,6 +214,13 @@ healthRouter.get('/models', async (req, res) => {
         enabled: durableJobs.enabled,
         protocolVersion: durableJobs.protocolVersion,
       },
+      transcription,
+      recovery: {
+        status: false,
+        restartWhisper: false,
+        restartServer: false,
+        managed: false,
+      },
       ...(localFirstMeetings ? { localFirstMeetings } : {}),
     },
   })

package/server/routes/transcribe-stream.ts

@@ -1,5 +1,6 @@
 // POST /api/transcribe-stream — Streaming transcription for continuous meeting capture
-// Uses local Whisper (50ms) with OpenAI API fallback.
+// Uses local Whisper. OpenAI API fallback is disabled by default and requires
+// both COS_OPENAI_WHISPER_FALLBACK=1 and a configured key.
 // Streams speaker-labeled transcript chunks for live meeting capture.
 
 import { Router } from 'express'
@@ -10,11 +11,13 @@ import { resolve } from 'node:path'
 import { fileURLToPath } from 'node:url'
 import { getVocabulary, getOwnerName } from '../lib/profile.js'
 import { getOpenAIKey } from '../lib/openai-key.js'
+import { getTranscriptionPolicySnapshot, isOpenAIWhisperFallbackReady } from '../lib/transcription-policy.js'
+import { TranscriptionUnavailableError } from '../lib/transcribe-audio.js'
 
 const __dirname = fileURLToPath(new URL('.', import.meta.url))
 import { emitDisplay } from '../lib/display-bus.js'
 import { errMsg } from '../lib/utils.js'
-import { transcribeLocal, isWhisperLocalAvailable, applyCorrections, type WhisperWord } from '../lib/whisper-local.js'
+import { transcribeLocal, applyCorrections, type WhisperWord } from '../lib/whisper-local.js'
 import { enhanceAudio } from '../lib/audio-enhance.js'
 import { trimSilence, isSileroAvailable } from '../lib/vad-silero.js'
 import { identifySpeaker, isEmbeddingAvailable, autoEnroll, getEmbeddingCount } from '../lib/speaker-embeddings.js'
@@ -1044,18 +1047,26 @@ function canonicalChunkResponse(
 }
 
 async function transcribeWithServerWhisper(audioBuffer: Buffer, whisperAudio: Buffer, whisperContext: string, isQuiet: boolean): Promise<{ text: string; words?: WhisperWord[]; backend: string }> {
-  if (isWhisperLocalAvailable()) {
-    try {
-      const result = await transcribeLocal(whisperAudio, whisperContext || undefined, isQuiet)
-      return { text: result.text, words: result.words, backend: `local-${result.backend}` }
-    } catch (err: unknown) {
-      console.warn(`[transcribe-stream] Local Whisper failed, falling back to cloud: ${errMsg(err)}`)
-      const text = await transcribeViaCloud(whisperAudio)
-      return { text, words: undefined, backend: 'cloud' }
+  // The worker owns reconciliation of stale health. Always attempt local ASR
+  // once; an availability snapshot must not divert meeting audio to cloud.
+  try {
+    const result = await transcribeLocal(whisperAudio, whisperContext || undefined, isQuiet)
+    return { text: result.text, words: result.words, backend: `local-${result.backend}` }
+  } catch (err: unknown) {
+    if (!isOpenAIWhisperFallbackReady()) {
+      const fallback = getTranscriptionPolicySnapshot()
+      console.warn(`[transcribe-stream] Local Whisper unavailable; preserving chunk for retry: ${errMsg(err)}`)
+      throw new TranscriptionUnavailableError(
+        fallback.openaiFallbackConfigured ? 'openai_key_missing' : 'local_asr_unavailable',
+        fallback.openaiFallbackConfigured
+          ? 'Local transcription is unavailable; audio is preserved for retry and the configured OpenAI fallback has no key'
+          : 'Local transcription is unavailable; audio is preserved for retry',
+      )
     }
+    console.warn(`[transcribe-stream] Local Whisper failed; using explicitly enabled OpenAI fallback: ${errMsg(err)}`)
+    const text = await transcribeViaCloud(whisperAudio)
+    return { text, words: undefined, backend: 'cloud' }
   }
-  const text = await transcribeViaCloud(whisperAudio)
-  return { text, words: undefined, backend: 'cloud' }
 }
 
 function identifyChunkSpeaker(audioBuffer: Buffer, sessionId: string, chunkIndex: number, clientSpeaker: string): { speaker: string; similarity: number } {
@@ -1315,6 +1326,14 @@ async function processStreamChunk(opts: {
 }
 
 function sendStreamError(res: { status: (code: number) => { json: (body: unknown) => unknown } }, err: unknown): unknown {
+  if (err instanceof TranscriptionUnavailableError) {
+    console.warn(`[transcribe-stream] ${err.message}`)
+    return res.status(err.status).json({
+      error: err.message,
+      reason: err.reason,
+      retryable: true,
+    })
+  }
   if (err instanceof OpenAIWhisperBudgetExhaustedError) {
     console.error(`[transcribe-stream] ${err.message}`)
     return res.status(503).json({
@@ -1487,9 +1506,18 @@ transcribeStreamRouter.post('/transcribe-stream/candidates', async (req, res) =>
  *  A hung whisper-server + long meeting is the exact scenario this guards against —
  *  chunks stay empty on budget-exceeded instead of silently billing per chunk. */
 async function transcribeViaCloud(audioBuffer: Buffer): Promise<string> {
-  assertOpenAIWhisperBudget()
+  if (!isOpenAIWhisperFallbackReady()) {
+    const fallback = getTranscriptionPolicySnapshot()
+    throw new TranscriptionUnavailableError(
+      fallback.openaiFallbackConfigured ? 'openai_key_missing' : 'local_asr_unavailable',
+      fallback.openaiFallbackConfigured
+        ? 'Local transcription is unavailable; audio is preserved for retry and the configured OpenAI fallback has no key'
+        : 'Local transcription is unavailable; audio is preserved for retry',
+    )
+  }
 
   const key = getOpenAIKey()
+  assertOpenAIWhisperBudget()
   const audioSeconds = estimateAudioSeconds(audioBuffer)
 
   const isWav = audioBuffer.length >= 4 && audioBuffer.toString('ascii', 0, 4) === 'RIFF'

package/server/routes/transcribe.ts

@@ -9,6 +9,7 @@ import {
   resolveTranscribeMode,
   NoSpeechDetectedError,
   OpenAIWhisperBudgetExhaustedError,
+  TranscriptionUnavailableError,
 } from '../lib/transcribe-audio.js'
 
 export const transcribeRouter = Router()
@@ -50,6 +51,14 @@ transcribeRouter.post('/transcribe', async (req, res) => {
         cap_usd: err.capUsd,
       })
     }
+    if (err instanceof TranscriptionUnavailableError) {
+      console.warn(`[transcribe] ${err.message}`)
+      return res.status(err.status).json({
+        error: err.message,
+        reason: err.reason,
+        retryable: true,
+      })
+    }
     res.status(500).json({ error: err.message })
   }
 })