@gotcos/glasses-server 6.11.0 → 6.12.1

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,60 @@
 # Changelog
 
+## 6.12.1
+
+Public-safe CLI diagnostics for the COS Glasses Recovery Center.
+
+- **Both local agents are visible.** Authenticated clients can inspect a
+  versioned Claude Code and Codex status summary at `/api/cli/debug`, including
+  provider support, persistence readiness, workspace configuration, and the
+  latest run's safe status metadata.
+- **False success is fenced.** Claude Code or Codex output that reports a
+  machine-shaped authentication failure while the CLI exits `0` is finalized
+  as a typed `auth_error`, never projected as a completed assistant reply.
+- **Build 210 stays compatible.** Sanitized `/api/cli/runs` and
+  `/api/codex/runs` projections preserve the fields older Recovery Centers can
+  render while newer clients adopt the combined contract.
+- **Diagnostics do not become an exfiltration path.** Responses use explicit
+  allowlists and omit commands, filesystem paths, trust modes, prompts,
+  answers, tool payloads, content previews, raw run/session/thread IDs,
+  resumable handles, environment values, and tokens. Legacy display IDs are
+  omitted and workspace state is a fixed label only.
+- **Authentication is mandatory.** All three diagnostic routes remain behind
+  the existing `/api` token boundary. Preview-enabled ledger fixtures are
+  covered by recursive forbidden-field and private-value tests.
+- **Unauthenticated health is capability-only.** `/api/health` and
+  `/api/models` advertise `capabilities.cliDebug`; health exposes only a CLI
+  session-availability boolean rather than the resumable session ID.
+- **Backward compatible.** Query, prompt, meeting, media, display, model, and
+  recovery behavior is unchanged. Older clients and servers continue to use
+  their existing paths; a missing CLI Debug capability remains an unsupported
+  feature rather than a connection failure.
+
+## 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.1",
   "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/index.ts

@@ -27,6 +27,7 @@ import { archiveRouter } from './routes/archive.js'
 import { sessionsRouter } from './routes/sessions.js'
 import { mediaRouter, mediaBodyParser } from './routes/media.js'
 import { promptDraftsRouter } from './routes/prompt-drafts.js'
+import { cliDebugRouter } from './routes/cli-debug.js'
 import { prewarmContext } from './lib/context-builder.js'
 import { preWarmCLI } from './lib/claude-bridge.js'
 import { getCodexRunConfig } from './lib/codex-run-ledger.js'
@@ -163,6 +164,7 @@ app.use('/api', archiveRouter)
 app.use('/api', sessionsRouter)
 app.use('/api', mediaRouter)
 app.use('/api', promptDraftsRouter)
+app.use('/api', cliDebugRouter)
 
 // OpenAI-compatible endpoint for the G2 Agent (ER "Add Agent")
 // Mounted at root — routes are /v1/chat/completions and /v1/models

package/server/lib/claude-bridge.ts

@@ -47,6 +47,7 @@ import {
   MAX_ATTACHMENTS_PER_PROMPT,
   type MediaAttachmentRef,
 } from '../../shared/media-attachment.js'
+import { terminalProviderAuthFailure } from './provider-terminal-error.js'
 
 // Inactivity = no stdout data for this long → kill (catches stalls)
 const INACTIVITY_BY_MODEL: Record<ClaudeModelPreference, number> = {
@@ -325,12 +326,15 @@ export interface StreamCallbacks {
 /** Claude CLI can emit `subtype: success` with `is_error: true`; the boolean
  * is authoritative and must win before session ids or result text are saved. */
 export function claudeResultErrorMessage(event: any): string | null {
-  if (event?.type !== 'result' || (event?.is_error !== true && event?.subtype !== 'error')) return null
+  if (event?.type !== 'result') return null
   const raw = typeof event?.result === 'string' ? event.result
     : typeof event?.error === 'string' ? event.error
     : typeof event?.error?.message === 'string' ? event.error.message
       : typeof event?.message === 'string' ? event.message
         : ''
+  const authFailure = terminalProviderAuthFailure('claude', raw, event?.error)
+  if (authFailure) return authFailure
+  if (event?.is_error !== true && event?.subtype !== 'error') return null
   const detail = raw.replace(/\s+/g, ' ').trim().slice(0, 240)
   return detail ? `claude-bridge: ${detail}` : 'claude-bridge: Claude CLI returned an error result.'
 }
@@ -545,6 +549,7 @@ export async function callClaudeStreaming(
   let stderr = ''
   let buffer = ''
   let finalized = false        // Guard against double onDone/onError
+  let terminalTextError: string | null = null
   let lastActivity = Date.now() // Tracks last stdout data for inactivity timeout
   let receivedStreamEvents = false  // Track if CLI emits stream_event (vs older assistant-only format)
   const toolInputs = new Map<number, { name: string; json: string }>()
@@ -570,6 +575,13 @@ export async function callClaudeStreaming(
 
   async function finalize(text: string) {
     if (finalized) return
+    const responseAuthFailure = terminalProviderAuthFailure('claude', text)
+    const authFailure = responseAuthFailure
+      ?? (!text.trim() ? terminalTextError ?? terminalProviderAuthFailure('claude', stderr) : null)
+    if (authFailure) {
+      await finalizeError(authFailure, 0)
+      return
+    }
     finalized = true
     cleanup()
     cleanupImages()
@@ -831,9 +843,16 @@ export async function callClaudeStreaming(
               text = event.content
             }
             if (text) {
-              phase = 'generating'
-              fullText += text
-              callbacks.onChunk(text)
+              // Withhold only strongly machine-shaped provider auth output so
+              // credentials cannot flash through onChunk. Human sign-in
+              // instructions do not match the terminal classifier.
+              const authFailure = terminalProviderAuthFailure('claude', text)
+              if (authFailure) terminalTextError = authFailure
+              else {
+                phase = 'generating'
+                fullText += text
+                callbacks.onChunk(text)
+              }
             }
           }
         } else if (event.type === 'user') {
@@ -855,7 +874,9 @@ export async function callClaudeStreaming(
         }
         // tool_use/tool_result/other events still reset inactivity (we got stdout data)
       } catch {
-        // Not valid JSON — ignore partial lines
+        // Older CLI builds can emit a terminal auth error as plain text while
+        // still exiting 0. Remember only the canonical classification.
+        terminalTextError ??= terminalProviderAuthFailure('claude', trimmed)
       }
     }
   })
@@ -883,13 +904,19 @@ export async function callClaudeStreaming(
       } catch { /* ignore */ }
     }
 
-    if (code !== 0 && !fullText) {
-      finalizeError(`claude-bridge: exit ${code} — ${stderr.trim().slice(0, 200)}`, code)
-    } else if (fullText) {
-      // If we got text but no explicit result event, still finalize
+    if (fullText) {
+      // If we got text but no explicit result event, still finalize. A sole,
+      // machine-shaped auth response is classified inside finalize.
       void finalize(fullText)
     } else {
-      finalizeError('claude-bridge: Claude completed without a response.', code)
+      const authFailure = terminalTextError ?? terminalProviderAuthFailure('claude', stderr, buffer)
+      if (authFailure) {
+        finalizeError(authFailure, code)
+      } else if (code !== 0) {
+        finalizeError(`claude-bridge: exit ${code} — ${stderr.trim().slice(0, 200)}`, code)
+      } else {
+        finalizeError('claude-bridge: Claude completed without a response.', code)
+      }
     }
   })
 

package/server/lib/cli-debug-view.ts

@@ -0,0 +1,213 @@
+import type { ClaudeRunConfig, ClaudeRunRecord } from './claude-run-ledger.js'
+import type { CodexRunConfig, CodexRunRecord } from './codex-run-ledger.js'
+
+export const CLI_DEBUG_CAPABILITY = Object.freeze({
+  schemaVersion: 1,
+  providers: Object.freeze({ claude: true, codex: true }),
+  metadataOnly: true,
+})
+
+export type SafeCliRunStatus =
+  | 'running'
+  | 'completed'
+  | 'failed'
+  | 'cancelled'
+  | 'client_disconnected'
+
+export interface SafeCliDebugLatestRun {
+  status: SafeCliRunStatus
+  model: string
+  concreteModel?: string
+  effort?: string
+  resumed: boolean
+  durationMs?: number
+  updatedAt: string
+  errorCode?: string
+}
+
+export interface SafeCliDebugProvider {
+  supported: true
+  persistenceEnabled: boolean
+  workspaceConfigured: boolean
+  latestRun: SafeCliDebugLatestRun | null
+}
+
+export interface SafeCliDebugResponse {
+  schemaVersion: 1
+  providers: {
+    claude: SafeCliDebugProvider
+    codex: SafeCliDebugProvider
+  }
+}
+
+function optionalString(value: unknown): string | undefined {
+  return typeof value === 'string' && value.trim() ? value.trim() : undefined
+}
+
+function optionalFiniteNumber(value: unknown): number | undefined {
+  return typeof value === 'number' && Number.isFinite(value) && value >= 0 ? value : undefined
+}
+
+function safeStatus(value: unknown): SafeCliRunStatus {
+  return value === 'running' || value === 'completed' || value === 'failed'
+    || value === 'cancelled' || value === 'client_disconnected'
+    ? value
+    : 'failed'
+}
+
+function safeModelLabel(value: unknown, provider: 'claude' | 'codex'): string | undefined {
+  const model = optionalString(value)
+  if (!model || model.length > 96) return undefined
+  const allowed = provider === 'claude'
+    ? /^(?:claude-|opus(?:\[1m\])?$|sonnet(?:\[1m\])?$|fable(?:\[1m\])?$|haiku(?:\[1m\])?$)[a-z0-9._\[\]-]*$/i
+    : /^(?:gpt-|codex-)[a-z0-9._\[\]-]*$/i
+  return allowed.test(model) ? model : undefined
+}
+
+function safeEffort(value: unknown): string | undefined {
+  const effort = optionalString(value)?.toLowerCase()
+  return effort && ['low', 'medium', 'high', 'xhigh', 'max', 'ultra', 'ultracode'].includes(effort)
+    ? effort
+    : undefined
+}
+
+function safeTimestamp(value: unknown): string {
+  const timestamp = optionalString(value)
+  const parsed = timestamp ? Date.parse(timestamp) : Number.NaN
+  return Number.isFinite(parsed) ? new Date(parsed).toISOString() : new Date(0).toISOString()
+}
+
+function safeErrorCode(provider: 'claude' | 'codex', value: unknown): string | undefined {
+  const candidate = optionalString(value)
+  if (!candidate) return undefined
+  const allowed = new Set([
+    `${provider}.cli_unavailable`,
+    `${provider}.permission_denied`,
+    `${provider}.auth_error`,
+    `${provider}.timeout`,
+    `${provider}.nonzero_exit`,
+    `${provider}.error`,
+    `${provider}.interrupted`,
+  ])
+  return allowed.has(candidate) ? candidate : `${provider}.error`
+}
+
+export function safeClaudeLatestRun(run?: ClaudeRunRecord): SafeCliDebugLatestRun | null {
+  if (!run) return null
+  const concreteModel = safeModelLabel(run.resolvedModelId ?? run.cliModelId, 'claude')
+  const effort = safeEffort(run.effortLevel)
+  const errorCode = safeErrorCode('claude', run.errorCode)
+  return {
+    status: safeStatus(run.status),
+    model: safeModelLabel(run.model, 'claude') ?? 'unknown',
+    ...(concreteModel ? { concreteModel } : {}),
+    ...(effort ? { effort } : {}),
+    resumed: run.resumed === true,
+    ...(optionalFiniteNumber(run.durationMs) !== undefined ? { durationMs: run.durationMs } : {}),
+    updatedAt: safeTimestamp(run.updatedAt),
+    ...(errorCode ? { errorCode } : {}),
+  }
+}
+
+export function safeCodexLatestRun(run?: CodexRunRecord): SafeCliDebugLatestRun | null {
+  if (!run) return null
+  const concreteModel = safeModelLabel(run.cliModel, 'codex')
+  const effort = safeEffort(run.reasoningEffort)
+  const errorCode = safeErrorCode('codex', run.errorCode)
+  return {
+    status: safeStatus(run.status),
+    model: safeModelLabel(run.model, 'codex') ?? 'unknown',
+    ...(concreteModel ? { concreteModel } : {}),
+    ...(effort ? { effort } : {}),
+    resumed: run.resumed === true,
+    ...(optionalFiniteNumber(run.durationMs) !== undefined ? { durationMs: run.durationMs } : {}),
+    updatedAt: safeTimestamp(run.updatedAt),
+    ...(errorCode ? { errorCode } : {}),
+  }
+}
+
+export function safeCliDebugResponse(
+  claudeConfig: ClaudeRunConfig,
+  claudeRun: ClaudeRunRecord | undefined,
+  codexConfig: CodexRunConfig,
+  codexRun: CodexRunRecord | undefined,
+): SafeCliDebugResponse {
+  return {
+    schemaVersion: 1,
+    providers: {
+      claude: {
+        supported: true,
+        persistenceEnabled: claudeConfig.persistenceEnabled === true,
+        workspaceConfigured: Boolean(claudeConfig.cwd),
+        latestRun: safeClaudeLatestRun(claudeRun),
+      },
+      codex: {
+        supported: true,
+        persistenceEnabled: codexConfig.persistenceEnabled === true,
+        workspaceConfigured: Boolean(codexConfig.cwd),
+        latestRun: safeCodexLatestRun(codexRun),
+      },
+    },
+  }
+}
+
+/** Compatibility projection for build 210 and earlier Settings panels.
+ * Every returned key is an explicit public-safe allowlist entry. */
+export function safeLegacyClaudeResponse(config: ClaudeRunConfig, runs: ClaudeRunRecord[]) {
+  return {
+    schemaVersion: 1,
+    config: {
+      persistenceEnabled: config.persistenceEnabled === true,
+      workspaceConfigured: Boolean(config.cwd),
+      cwd: config.cwd ? 'Configured workspace' : 'Not configured',
+      defaultEffortLevel: safeEffort(config.defaultEffortLevel) ?? 'high',
+      contentPreviewsEnabled: false,
+    },
+    runs: runs.map(run => {
+      const latest = safeClaudeLatestRun(run)!
+      return {
+        status: latest.status,
+        model: latest.model,
+        ...(latest.concreteModel ? {
+          cliModelId: latest.concreteModel,
+          resolvedModelId: latest.concreteModel,
+        } : {}),
+        ...(latest.effort ? { effortLevel: latest.effort } : {}),
+        ...(typeof latest.resumed === 'boolean' ? { resumed: latest.resumed } : {}),
+        ...(latest.durationMs !== undefined ? { durationMs: latest.durationMs } : {}),
+        ...(latest.updatedAt ? { updatedAt: latest.updatedAt } : {}),
+        ...(latest.errorCode ? { errorCode: latest.errorCode } : {}),
+      }
+    }),
+  }
+}
+
+/** Compatibility projection for build 210 and earlier Settings panels.
+ * Engine sessions are deliberately absent: their thread ids are resumable
+ * runtime handles, not display metadata. */
+export function safeLegacyCodexResponse(config: CodexRunConfig, runs: CodexRunRecord[]) {
+  return {
+    schemaVersion: 1,
+    config: {
+      persistenceEnabled: config.persistenceEnabled === true,
+      workspaceConfigured: Boolean(config.cwd),
+      cwd: config.cwd ? 'Configured workspace' : 'Not configured',
+      cliModel: safeModelLabel(config.cliModel, 'codex') ?? 'unknown',
+      reasoningEffort: safeEffort(config.reasoningEffort) ?? 'high',
+      contentPreviewsEnabled: false,
+    },
+    runs: runs.map(run => {
+      const latest = safeCodexLatestRun(run)!
+      return {
+        status: latest.status,
+        model: latest.model,
+        ...(latest.concreteModel ? { cliModel: latest.concreteModel } : {}),
+        ...(latest.effort ? { reasoningEffort: latest.effort } : {}),
+        ...(typeof latest.resumed === 'boolean' ? { resumed: latest.resumed } : {}),
+        ...(latest.durationMs !== undefined ? { durationMs: latest.durationMs } : {}),
+        ...(latest.updatedAt ? { updatedAt: latest.updatedAt } : {}),
+        ...(latest.errorCode ? { errorCode: latest.errorCode } : {}),
+      }
+    }),
+  }
+}

package/server/lib/codex-bridge.ts

@@ -60,6 +60,7 @@ import {
   MAX_ATTACHMENTS_PER_PROMPT,
   type MediaAttachmentRef,
 } from '../../shared/media-attachment.js'
+import { terminalProviderAuthFailure } from './provider-terminal-error.js'
 
 const INACTIVITY_MS = 180_000
 const WALL_MAX_MS = 900_000
@@ -366,6 +367,7 @@ export async function callCodexStreaming(
   let stderr = ''
   let buffer = ''
   let finalized = false
+  let terminalTextError: string | null = null
   let lastActivity = Date.now()
   const emittedBlocks = new Set<string>()
 
@@ -425,6 +427,13 @@ export async function callCodexStreaming(
 
   async function finalize(text: string) {
     if (finalized) return
+    const responseAuthFailure = terminalProviderAuthFailure('codex', text)
+    const authFailure = responseAuthFailure
+      ?? (!text.trim() ? terminalTextError ?? terminalProviderAuthFailure('codex', stderr) : null)
+    if (authFailure) {
+      await finalizeError(authFailure, 0)
+      return
+    }
     finalized = true
     cleanup()
     cleanupImages()
@@ -614,13 +623,32 @@ export async function callCodexStreaming(
     }
 
     const text = extractCodexResponseText(event)
-    if (text) emitText(text)
+    if (text) {
+      // Withhold only strongly machine-shaped provider auth output so
+      // credentials cannot flash through onChunk. Human sign-in instructions
+      // do not match the terminal classifier.
+      const authFailure = terminalProviderAuthFailure('codex', text)
+      if (authFailure) terminalTextError = authFailure
+      else emitText(text)
+    }
 
     const type = String(event?.type ?? '')
     if (type === 'turn.completed') {
       void finalize(fullText)
     } else if (type === 'turn.failed' || type === 'error') {
-      finalizeError(`codex-bridge: ${event?.error ?? event?.message ?? 'unknown error'}`)
+      const rawProviderError = typeof event?.error === 'string' ? event.error
+        : typeof event?.error?.message === 'string' ? event.error.message
+          : typeof event?.message === 'string' ? event.message
+            : 'unknown error'
+      const structuredProviderError = event?.error && typeof event.error === 'object'
+        ? JSON.stringify(event.error)
+        : ''
+      const authenticationError = terminalProviderAuthFailure(
+        'codex',
+        rawProviderError,
+        structuredProviderError,
+      )
+      finalizeError(authenticationError ?? `codex-bridge: ${rawProviderError}`)
     }
   }
 
@@ -636,7 +664,9 @@ export async function callCodexStreaming(
       try {
         handleEvent(JSON.parse(trimmed))
       } catch {
-        // Ignore non-JSON status lines from older CLI builds.
+        // Older CLI builds can emit a terminal auth error as plain text while
+        // still exiting 0. Remember only the canonical classification.
+        terminalTextError ??= terminalProviderAuthFailure('codex', trimmed)
       }
     }
   })
@@ -651,10 +681,15 @@ export async function callCodexStreaming(
       try { handleEvent(JSON.parse(buffer.trim())) } catch { /* ignore */ }
     }
     if (finalized) return
-    if (code !== 0) {
-      finalizeError(`codex-bridge: exit ${code} — ${stderr.trim().slice(0, 240)}`, code)
-    } else if (fullText) {
+    if (fullText) {
       void finalize(fullText)
+      return
+    }
+    const authFailure = terminalTextError ?? terminalProviderAuthFailure('codex', stderr, buffer)
+    if (authFailure) {
+      finalizeError(authFailure, code)
+    } else if (code !== 0) {
+      finalizeError(`codex-bridge: exit ${code} — ${stderr.trim().slice(0, 240)}`, code)
     } else {
       finalizeError('codex-bridge: Codex completed without a response.')
     }

package/server/lib/provider-terminal-error.ts

@@ -0,0 +1,55 @@
+export type CliProvider = 'claude' | 'codex'
+
+const AUTH_CODE = /^(?:401|403|unauthori[sz]ed|forbidden|authentication_error|authorization_error|invalid_api_key|not_authenticated)$/i
+// Match whole, terminal-looking provider failures only. Natural assistant
+// answers such as "Please sign in to the customer portal, then..." must not
+// be reinterpreted as failures merely because their first words mention auth.
+const AUTH_FAILURE_PREFIX = /^(?:\s*(?:api\s+|http\s+|request\s+)?error(?:\[[^\]]+\])?\s*:\s*.{0,180}\b(?:401|403|unauthori[sz]ed|forbidden|authentication\s+(?:failed|required)|login\s+required|not\s+(?:logged|signed)\s+in)\b.*|\s*(?:http\s+)?(?:401|403)(?:\s+(?:unauthori[sz]ed|forbidden))?(?:\s*[:.\-]\s*.*)?|\s*(?:unauthori[sz]ed|forbidden)(?:\s*[:.\-]\s*.*)?|\s*(?:authentication|authorization)\s+(?:failed|required|error|missing|denied)(?:\s*[:.\-]\s*.*)?|\s*(?:login|sign[ -]?in)\s+(?:required|failed)(?:\s*[:.\-]\s*.*)?|\s*(?:you(?:'re| are)\s+)?not\s+(?:logged|signed)\s+in(?:\s*[:.\-]\s*.*)?|\s*please\s+run\s+(?:[`'"]?(?:claude|codex)[`'"]?\s+)?(?:[`'"]?\/?login[`'"]?|[`'"]?auth(?:enticate)?[`'"]?)\b.*)\s*$/i
+
+function stripAnsi(value: string): string {
+  // eslint-disable-next-line no-control-regex
+  return value.replace(/\u001b\[[0-?]*[ -/]*[@-~]/g, '')
+}
+
+function structuredAuthFailure(value: unknown): boolean {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) return false
+  const record = value as Record<string, unknown>
+  if (record.status === 401 || record.status === 403 || record.statusCode === 401 || record.statusCode === 403) return true
+  for (const key of ['code', 'type']) {
+    if (typeof record[key] === 'string' && AUTH_CODE.test(record[key])) return true
+  }
+  if (typeof record.error === 'string') {
+    return AUTH_CODE.test(record.error.trim()) || AUTH_FAILURE_PREFIX.test(record.error)
+  }
+  return structuredAuthFailure(record.error)
+}
+
+function looksLikeTerminalAuthFailure(value: unknown): boolean {
+  if (value && typeof value === 'object' && !Array.isArray(value)) {
+    return structuredAuthFailure(value)
+  }
+  if (typeof value !== 'string') return false
+  const text = stripAnsi(value).trim()
+  if (!text || text.length > 2_000) return false
+  if (AUTH_FAILURE_PREFIX.test(text.replace(/\s+/g, ' '))) return true
+  if (!(text.startsWith('{') && text.endsWith('}'))) return false
+  try {
+    return structuredAuthFailure(JSON.parse(text))
+  } catch {
+    return false
+  }
+}
+
+/**
+ * Some CLI versions report authentication failures as successful process
+ * output and exit 0. Detect only terminal, machine-shaped auth messages and
+ * return a canonical error that cannot echo credentials or provider output.
+ */
+export function terminalProviderAuthFailure(
+  provider: CliProvider,
+  ...terminalValues: unknown[]
+): string | null {
+  return terminalValues.some(looksLikeTerminalAuthFailure)
+    ? `${provider}-bridge: authentication required.`
+    : null
+}

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/cli-debug.ts

@@ -0,0 +1,66 @@
+import { Router } from 'express'
+import { normalizeModelPreference, isClaudeModel } from '../../shared/model-preference.js'
+import {
+  getClaudeRunConfig,
+  listClaudeRuns,
+} from '../lib/claude-run-ledger.js'
+import {
+  getCodexRunConfig,
+  listCodexRuns,
+} from '../lib/codex-run-ledger.js'
+import {
+  safeCliDebugResponse,
+  safeLegacyClaudeResponse,
+  safeLegacyCodexResponse,
+} from '../lib/cli-debug-view.js'
+
+export const cliDebugRouter = Router()
+
+function boundedLimit(value: unknown): number {
+  const raw = Number(value ?? 20)
+  return Number.isFinite(raw) && raw > 0 ? Math.min(Math.floor(raw), 50) : 20
+}
+
+function optionalSessionId(value: unknown): string | undefined {
+  return typeof value === 'string' && value.trim() ? value.trim() : undefined
+}
+
+function optionalClaudeModel(value: unknown) {
+  const raw = typeof value === 'string' ? normalizeModelPreference(value) : undefined
+  return raw && isClaudeModel(raw) ? raw : undefined
+}
+
+// Versioned public-safe view consumed by Recovery Center. Global /api auth
+// protects this route; it must never be added to the unauthenticated allowlist.
+cliDebugRouter.get('/cli/debug', (req, res) => {
+  const limit = boundedLimit(req.query.limit)
+  const sessionId = optionalSessionId(req.query.sessionId)
+  const model = optionalClaudeModel(req.query.model)
+  const claudeConfig = getClaudeRunConfig()
+  const codexConfig = getCodexRunConfig()
+  const claudeRuns = listClaudeRuns(limit, sessionId, model)
+  const codexRuns = listCodexRuns(limit, sessionId)
+  res.json(safeCliDebugResponse(
+    claudeConfig,
+    claudeRuns[0],
+    codexConfig,
+    codexRuns[0],
+  ))
+})
+
+// Build-210 compatibility. These legacy shapes retain only the fields the old
+// panel can render safely; they do not expose raw ledger records.
+cliDebugRouter.get('/cli/runs', (req, res) => {
+  const limit = boundedLimit(req.query.limit)
+  const sessionId = optionalSessionId(req.query.sessionId)
+  const model = optionalClaudeModel(req.query.model)
+  const config = getClaudeRunConfig()
+  res.json(safeLegacyClaudeResponse(config, listClaudeRuns(limit, sessionId, model)))
+})
+
+cliDebugRouter.get('/codex/runs', (req, res) => {
+  const limit = boundedLimit(req.query.limit)
+  const sessionId = optionalSessionId(req.query.sessionId)
+  const config = getCodexRunConfig()
+  res.json(safeLegacyCodexResponse(config, listCodexRuns(limit, sessionId)))
+})

package/server/routes/health.ts

@@ -19,6 +19,8 @@ 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'
+import { CLI_DEBUG_CAPABILITY } from '../lib/cli-debug-view.js'
 
 export const healthRouter = Router()
 
@@ -52,7 +54,7 @@ function durableQueryJobStatus() {
 }
 
 healthRouter.get('/health', async (_req, res) => {
-  const checks: Record<string, string | number> = {
+  const checks: Record<string, string | number | boolean> = {
     status: 'ok',
     mode: COS_MODE ? 'cos' : 'standalone',
     server: 'ok',
@@ -127,9 +129,11 @@ healthRouter.get('/health', async (_req, res) => {
 
   checks.silero_vad = isSileroAvailable() ? 'active' : 'disabled'
 
-  // Include CLI session ID if available (pre-warmed or active)
+  // Health is unauthenticated. Publish only availability; the actual CLI
+  // session id is a resumable runtime handle and belongs on authenticated
+  // query/debug surfaces.
   const cliSid = getAvailableCliSessionId()
-  if (cliSid) checks.cli_session_id = cliSid
+  checks.cli_session_available = Boolean(cliSid)
 
   // Feature summary for client capability detection.
   // v5.9.5 — voice.hasKey reflects the centralized resolver (env > saved file >
@@ -140,6 +144,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 +165,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 +185,12 @@ healthRouter.get('/health', async (_req, res) => {
     whisper_health,
     openai_whisper_budget,
     codex_models,
-    capabilities: localFirstMeetings ? { localFirstMeetings } : {},
+    capabilities: {
+      transcription,
+      recovery,
+      cliDebug: CLI_DEBUG_CAPABILITY,
+      ...(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 +209,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 +218,14 @@ healthRouter.get('/models', async (req, res) => {
         enabled: durableJobs.enabled,
         protocolVersion: durableJobs.protocolVersion,
       },
+      transcription,
+      cliDebug: CLI_DEBUG_CAPABILITY,
+      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 })
   }
 })