@gotcos/glasses-server 6.20.1 → 6.21.0

package/.env.example

@@ -83,6 +83,13 @@ BIND_HOST=0.0.0.0
 # COS_HQ_SPECULATIVE_WARM=0        # disable background HQ warm
 # COS_BATCH_LARGE_V3=0             # explicitly use turbo instead of full HQ
 # COS_HQ_BEAM_INTERACTIVE=2        # interactive only; meetings stay at beam 5
+# Control owns the machine-wide tier. Balanced is recommended: Small.en is a
+# cosmetic prompt preview only, while Turbo commits authoritative live text and
+# Large-v3 polishes saved work. Max reuses the resident Large-v3 worker for
+# preview + commit; it is opt-in for powerful Macs and never starts a third
+# Whisper worker.
+# COS_WHISPER_TRANSCRIPTION_TIER=balanced   # balanced | max
+# COS_WHISPER_COMMIT_MODEL=turbo            # turbo | large-v3 (advanced override)
 # Adaptive prompt transcription keeps three quality lanes separate:
 #   Small.en provisional preview -> Large-v3-Turbo committed live text -> Large-v3 HQ polish.
 # Unset preserves the pre-6.20 Turbo behavior. `auto` uses Small.en when it has

package/CHANGELOG.md

@@ -1,3 +1,27 @@
+## 6.21.0
+
+Transcription quality is now a machine-owned, observable two-tier policy.
+
+- **Balanced and Max tiers.** Balanced keeps Small.en as a cosmetic prompt
+  preview, Large-v3-Turbo as the authoritative live commit model, and Large-v3
+  for saved-work polish. Max reuses the resident Large-v3 worker for preview
+  and commit; it never starts a third Whisper process.
+- **Safe Large-v3 fallback.** A requested Max tier degrades visibly to Turbo
+  when the Large-v3 weights are unavailable. Immutable Turbo and Large-v3
+  paths remain independently addressable for fallback and HQ work; health also
+  warns when Max is active but its immutable Turbo recovery weights are absent.
+- **Preview isolation.** Small.en previews no longer receive decoder-bias
+  vocabulary and still cannot write recovery state or replace committed text.
+  Startup reaps only an exact stale Small.en/8177 worker before spawning its
+  owned child; an unrelated listener is never contacted with audio or killed.
+- **Truthful health.** The existing
+  `capabilities.transcription.live` block now reports requested/effective tier,
+  requested/effective commit model, downgrade reason, and preview prompt policy
+  without exposing local file paths.
+- **Guided provisioning.** `--setup-transcription --transcription-tier
+  balanced|max` provisions only the models required by the selected tier plus
+  the immutable Turbo fallback and Large-v3 HQ model.
+
 ## 6.20.1
 
 Adaptive setup now survives the slow or interrupted downloads that exposed the

package/README.md

@@ -236,20 +236,34 @@ Prompt dictation defaults to HQ. The phone owns the preference: **Fast mode
 OFF** requests HQ, and **Fast mode ON** requests turbo. The Mac performs all
 decoding; the phone does not run Whisper.
 
-For the recommended adaptive setup, run:
+For the recommended **Balanced** setup, run:
 
 ```bash
-npx --yes @gotcos/glasses-server@latest --setup-transcription
+npx --yes @gotcos/glasses-server@latest --setup-transcription --transcription-tier balanced
 ```
 
-That keeps three jobs separate: Small.en supplies provisional words on the
-lens, Large-v3-Turbo commits the authoritative live transcript, and Large-v3
-polishes saved prompts and meetings. Small.en never writes the recovery ledger.
+That keeps three jobs separate: Small.en supplies provisional prompt words on
+the lens, Large-v3-Turbo commits the authoritative live transcript, and
+Large-v3 polishes saved prompts and meetings. Small.en never writes the
+recovery ledger and receives no decoder-bias prompt.
 If its sidecar is missing or unhealthy, preview falls back to Turbo without
 changing final quality. Set `COS_WHISPER_PREVIEW_MODEL=turbo` to keep one live
 model, or `off` to disable provisional peeks. Existing installs that only
 update the server remain on Turbo until Guided Setup opts them into Small.en.
 
+**Max** is an opt-in tier for powerful Macs:
+
+```bash
+npx --yes @gotcos/glasses-server@latest --setup-transcription --transcription-tier max
+```
+
+Max reuses the existing Large-v3 worker for preview and authoritative commit;
+saved work still receives Large-v3 HQ polish. It does not start a third model
+process. If Large-v3 is missing, health reports the downgrade and the server
+falls back to Turbo rather than making transcription unavailable. COS Control
+is the supported owner of the machine-wide tier; the per-lane environment
+variables remain advanced overrides.
+
 The first server start downloads the real-time turbo model. True HQ additionally
 requires the full `ggml-large-v3.bin` model (about 3.1 GB):
 

package/bin/cli.cjs

@@ -26,6 +26,20 @@ const PKG_ROOT = resolve(__dirname, '..')
 const CONFIG_DIR = join(homedir(), '.cos-glasses')
 const PREPARE_ONLY = process.argv.includes('--prepare-only')
 const SETUP_TRANSCRIPTION = process.argv.includes('--setup-transcription')
+function optionValue(name) {
+  const index = process.argv.indexOf(name)
+  return index >= 0 ? process.argv[index + 1] : undefined
+}
+const TRANSCRIPTION_TIER_RAW = optionValue('--transcription-tier')
+const TRANSCRIPTION_TIER = TRANSCRIPTION_TIER_RAW?.trim().toLowerCase() || 'balanced'
+if (process.argv.includes('--transcription-tier') && !TRANSCRIPTION_TIER_RAW) {
+  console.error('Missing value for --transcription-tier. Use balanced or max.')
+  process.exit(64)
+}
+if (TRANSCRIPTION_TIER_RAW && !['balanced', 'max'].includes(TRANSCRIPTION_TIER)) {
+  console.error(`Invalid --transcription-tier "${TRANSCRIPTION_TIER_RAW}". Use balanced or max.`)
+  process.exit(64)
+}
 
 // Record where the user ran `npx @gotcos/glasses-server` from. The server spawns
 // with cwd = PKG_ROOT (the npx cache), so without this the user's Starter-Kit COS
@@ -46,6 +60,7 @@ if (process.argv.includes('--help') || process.argv.includes('-h')) {
   console.log('  Usage:')
   console.log('    npx --yes @gotcos/glasses-server@latest')
   console.log('    npx --yes @gotcos/glasses-server@latest --setup-transcription')
+  console.log('    npx --yes @gotcos/glasses-server@latest --setup-transcription --transcription-tier balanced|max')
   console.log('    npx --yes @gotcos/glasses-server@latest --prepare-only')
   console.log('')
   console.log('  Requirements:')
@@ -355,9 +370,18 @@ function upsertEnvValue(file, key, value) {
 }
 
 if (SETUP_TRANSCRIPTION) {
-  upsertEnvValue(ENV_FILE, 'COS_WHISPER_PREVIEW_MODEL', 'small.en')
-  process.env.COS_WHISPER_PREVIEW_MODEL = 'small.en'
-  console.log(green('  ✓') + ' Adaptive transcription selected ' + dim('— Small.en preview · Turbo commit · Large-v3 HQ'))
+  const previewModel = TRANSCRIPTION_TIER === 'max' ? 'turbo' : 'small.en'
+  const commitModel = TRANSCRIPTION_TIER === 'max' ? 'large-v3' : 'turbo'
+  upsertEnvValue(ENV_FILE, 'COS_WHISPER_TRANSCRIPTION_TIER', TRANSCRIPTION_TIER)
+  upsertEnvValue(ENV_FILE, 'COS_WHISPER_PREVIEW_MODEL', previewModel)
+  upsertEnvValue(ENV_FILE, 'COS_WHISPER_COMMIT_MODEL', commitModel)
+  process.env.COS_WHISPER_TRANSCRIPTION_TIER = TRANSCRIPTION_TIER
+  process.env.COS_WHISPER_PREVIEW_MODEL = previewModel
+  process.env.COS_WHISPER_COMMIT_MODEL = commitModel
+  const laneSummary = TRANSCRIPTION_TIER === 'max'
+    ? 'Large-v3 preview + commit · Large-v3 HQ'
+    : 'Small.en preview · Turbo commit · Large-v3 HQ'
+  console.log(green('  ✓') + ` ${TRANSCRIPTION_TIER === 'max' ? 'Max' : 'Balanced'} transcription selected ` + dim(`— ${laneSummary}`))
 }
 // Persistent profile (identity + transcription vocabulary)
 const PROFILE_FILE = join(CONFIG_DIR, '.cos-profile.json')
@@ -446,7 +470,7 @@ const transcriptionSetupFailures = []
 
 if (SETUP_TRANSCRIPTION && (!whisperCliPath || !whisperServerPath)) {
   console.log('')
-  console.log(red('  ✗ Adaptive transcription needs whisper.cpp'))
+  console.log(red('  ✗ Transcription setup needs whisper.cpp'))
   console.log('    Install it first: ' + bold('brew install whisper-cpp'))
   console.log('    Then rerun this setup command. No model download was started.')
   console.log('')
@@ -457,7 +481,9 @@ if (SETUP_TRANSCRIPTION && process.env.SKIP_WHISPER_DOWNLOAD !== '1') {
   mkdirSync(WHISPER_MODEL_DIR, { recursive: true })
   const targets = [
     [WHISPER_MODEL_PATH, WHISPER_MODEL_PARTIAL, WHISPER_MODEL_MIN_BYTES, WHISPER_MODEL_EXPECTED_BYTES],
-    [WHISPER_SMALL_MODEL_PATH, WHISPER_SMALL_MODEL_PARTIAL, WHISPER_SMALL_MODEL_MIN_BYTES, WHISPER_SMALL_MODEL_EXPECTED_BYTES],
+    ...(TRANSCRIPTION_TIER === 'balanced'
+      ? [[WHISPER_SMALL_MODEL_PATH, WHISPER_SMALL_MODEL_PARTIAL, WHISPER_SMALL_MODEL_MIN_BYTES, WHISPER_SMALL_MODEL_EXPECTED_BYTES]]
+      : []),
     [WHISPER_LARGE_MODEL_PATH, WHISPER_LARGE_MODEL_PARTIAL, WHISPER_LARGE_MODEL_MIN_BYTES, WHISPER_LARGE_MODEL_EXPECTED_BYTES],
   ]
   const missingBytes = targets.reduce((sum, [path, , minimum, expected]) =>
@@ -472,7 +498,7 @@ if (SETUP_TRANSCRIPTION && process.env.SKIP_WHISPER_DOWNLOAD !== '1') {
     const requiredGB = ((missingBytes + safetyMarginBytes) / 1_000_000_000).toFixed(1)
     const availableGB = (availableBytes / 1_000_000_000).toFixed(1)
     console.log('')
-    console.log(red('  ✗ Not enough free disk space for adaptive transcription'))
+    console.log(red('  ✗ Not enough free disk space for transcription setup'))
     console.log(`    Need about ${requiredGB} GB; ${availableGB} GB is available after reusable partial downloads.`)
     console.log('    Free space, then rerun this setup command. Existing models were not removed.')
     console.log('')
@@ -550,10 +576,13 @@ if (whisperCliPath && wantsSmallPreview) {
 
 if (whisperCliPath && SETUP_TRANSCRIPTION) {
   if (isValidWhisperModel(WHISPER_LARGE_MODEL_PATH, WHISPER_LARGE_MODEL_MIN_BYTES)) {
-    console.log(green('  ✓') + ' Large-v3 HQ model ready ' + dim('— saved meetings use full polish'))
+    const largeRole = TRANSCRIPTION_TIER === 'max'
+      ? 'live preview + commit and saved-meeting polish'
+      : 'saved meetings use full polish'
+    console.log(green('  ✓') + ' Large-v3 model ready ' + dim(`— ${largeRole}`))
   } else {
     if (existsSync(WHISPER_LARGE_MODEL_PATH)) { try { unlinkSync(WHISPER_LARGE_MODEL_PATH) } catch {} }
-    console.log(yellow('  ⚠') + ' HQ polish model missing')
+    console.log(yellow('  ⚠') + ' Large-v3 model missing')
     console.log('    ' + dim('Downloading ggml-large-v3 (~3.1 GB).'))
     if (process.env.SKIP_WHISPER_DOWNLOAD === '1') {
       console.log(yellow('  ⚠') + ' SKIP_WHISPER_DOWNLOAD=1 — HQ safely reports unavailable and live Turbo continues')
@@ -566,12 +595,12 @@ if (whisperCliPath && SETUP_TRANSCRIPTION) {
           expectedBytes: WHISPER_LARGE_MODEL_EXPECTED_BYTES,
           timeoutMs: 7_200_000,
         })
-        console.log(green('  ✓') + ' Large-v3 HQ model downloaded')
+        console.log(green('  ✓') + ' Large-v3 model downloaded')
       } catch (err) {
         console.log(red('  ✗') + ' Large-v3 download failed ' + dim('— live Turbo remains available'))
         console.log('    ' + dim('Error: ' + (err.message || err).toString().slice(0, 120)))
         console.log('    ' + dim('Partial download retained; rerun setup to resume it.'))
-        transcriptionSetupFailures.push('Large-v3 HQ model')
+        transcriptionSetupFailures.push(TRANSCRIPTION_TIER === 'max' ? 'Large-v3 Max/HQ model' : 'Large-v3 HQ model')
       }
     }
   }
@@ -580,13 +609,13 @@ if (whisperCliPath && SETUP_TRANSCRIPTION) {
 if (PREPARE_ONLY && SETUP_TRANSCRIPTION) {
   console.log('')
   if (transcriptionSetupFailures.length > 0) {
-    console.log(red('  ✗ Adaptive transcription setup incomplete'))
+    console.log(red('  ✗ Transcription setup incomplete'))
     console.log('    Missing: ' + transcriptionSetupFailures.join(', '))
     console.log('    Rerun this command; retained downloads resume from the last byte received.')
     console.log('')
     process.exit(1)
   }
-  console.log(green('  ✓ Adaptive transcription setup complete'))
+  console.log(green('  ✓ Transcription setup complete'))
   console.log('    Return to COS Control and Restart, install, or update the managed server.')
   console.log('')
   process.exit(0)

package/package.json

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

package/server/index.ts

@@ -298,7 +298,7 @@ async function gracefulShutdown(): Promise<void> {
   try { logActiveSessionsOnShutdown() } catch { /* best-effort flush */ }
   stopCodexModelCatalogRefresh()
   stopWhisperServer()
-  stopWhisperPreviewServer()
+  await stopWhisperPreviewServer()
   stopLocalTtsServer()
   clearTimeout(forceExit)
   process.exit(0)

package/server/lib/whisper-local.ts

@@ -107,22 +107,76 @@ function resolveWhisperBin(name: string): string {
 }
 const WHISPER_CLI = resolveWhisperBin('whisper-cli')
 const WHISPER_SERVER = resolveWhisperBin('whisper-server')
-const MODEL_PATH = join(process.env.HOME ?? homedir(), '.local/share/whisper-models/ggml-large-v3-turbo.bin')
+const MODEL_DIR = join(process.env.HOME ?? homedir(), '.local/share/whisper-models')
+export const WHISPER_TURBO_MODEL_PATH = join(MODEL_DIR, 'ggml-large-v3-turbo.bin')
+export const WHISPER_LARGE_V3_MODEL_PATH = join(MODEL_DIR, 'ggml-large-v3.bin')
+
+export type WhisperCommitRequest = 'turbo' | 'large-v3'
+export type WhisperCommitModel = 'large-v3-turbo' | 'large-v3'
+export type WhisperTranscriptionTier = 'balanced' | 'max'
+
+export interface WhisperCommitCapability {
+  requestedTier: WhisperTranscriptionTier
+  effectiveTier: WhisperTranscriptionTier
+  requestedModel: WhisperCommitRequest
+  effectiveModel: WhisperCommitModel
+  ready: boolean
+  configured: boolean
+  degraded: boolean
+  reason: 'large_v3_model_missing' | 'turbo_model_missing' | null
+  promptPolicy: 'full-vocabulary'
+}
+
+export function normalizeWhisperTranscriptionTier(raw?: string): WhisperTranscriptionTier {
+  return raw?.trim().toLowerCase() === 'max' ? 'max' : 'balanced'
+}
+
+export function normalizeWhisperCommitRequest(raw?: string): WhisperCommitRequest {
+  const value = raw?.trim().toLowerCase()
+  if (value === 'large-v3' || value === 'large_v3' || value === 'ggml-large-v3.bin' || value === 'max') {
+    return 'large-v3'
+  }
+  return 'turbo'
+}
+
+function requestedTranscriptionTier(): WhisperTranscriptionTier {
+  return normalizeWhisperTranscriptionTier(process.env.COS_WHISPER_TRANSCRIPTION_TIER)
+}
+
+function requestedCommitModel(): WhisperCommitRequest {
+  const explicit = process.env.COS_WHISPER_COMMIT_MODEL
+  return explicit
+    ? normalizeWhisperCommitRequest(explicit)
+    : requestedTranscriptionTier() === 'max' ? 'large-v3' : 'turbo'
+}
+
+const COMMIT_REQUEST = requestedCommitModel()
+const REQUESTED_TRANSCRIPTION_TIER = requestedTranscriptionTier()
+const COMMIT_MODEL_PATH = COMMIT_REQUEST === 'large-v3' && existsSync(WHISPER_LARGE_V3_MODEL_PATH)
+  ? WHISPER_LARGE_V3_MODEL_PATH
+  : WHISPER_TURBO_MODEL_PATH
+const COMMIT_MODEL: WhisperCommitModel = COMMIT_MODEL_PATH === WHISPER_LARGE_V3_MODEL_PATH
+  ? 'large-v3'
+  : 'large-v3-turbo'
+
+if (COMMIT_REQUEST === 'large-v3' && COMMIT_MODEL !== 'large-v3') {
+  console.warn('[whisper-local] Max requested but Large-v3 weights are missing; committed transcription is using Turbo.')
+}
 
 // Post-meeting batch transcription uses the full 32-layer Whisper large-v3
 // instead of turbo's 4-layer decoder. Bake-off on 2026-04-16 showed the full
 // decoder captures +43% more speech content with zero known-hallucinations on
 // a real 23.6 min G2 recording. See wk16_2026/asr-bakeoff/report.md.
 //
-// Streaming path stays on turbo (whisper-server + VAD) for latency. Only the
-// post-meeting HQ re-transcription uses large-v3 — runs fire-and-forget after
-// meeting save, so the ~4x wall-time cost is invisible to the user.
+// Balanced live commit stays on Turbo. Max may opt the persistent live worker
+// into Large-v3 on measured hardware. Post-meeting HQ remains a separate batch
+// policy and never inherits the live commit selection.
 //
 // DISABLE: set COS_BATCH_LARGE_V3=0 to revert HQ path to turbo. Missing-weights
 // case is defensive: if ggml-large-v3.bin isn't on disk we log a warning and
 // fall back to turbo automatically — no broken batch runs.
-const BATCH_MODEL_LARGE_V3 = join(process.env.HOME ?? homedir(), '.local/share/whisper-models/ggml-large-v3.bin')
-const BATCH_MODEL_TURBO = MODEL_PATH
+const BATCH_MODEL_LARGE_V3 = WHISPER_LARGE_V3_MODEL_PATH
+const BATCH_MODEL_TURBO = WHISPER_TURBO_MODEL_PATH
 const BATCH_LARGE_V3_ENABLED = process.env.COS_BATCH_LARGE_V3 !== '0'
 
 // Silero VAD (ggml) — whisper-server --vad strips silence/noise windows BEFORE the
@@ -286,7 +340,9 @@ function isCosWhisperServerCommand(command: string): boolean {
   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)
+  const supportedModel = [WHISPER_TURBO_MODEL_PATH, WHISPER_LARGE_V3_MODEL_PATH]
+    .some(modelPath => command.includes(modelPath))
+  return executable && configuredPort && supportedModel
 }
 
 function collectDescendants(processes: ProcessEntry[], roots: Iterable<number>): Set<number> {
@@ -399,7 +455,9 @@ async function proveWhisperPortClear(): Promise<void> {
 
 // Check CLI availability at import time
 try {
-  cliAvailable = existsSync(WHISPER_CLI) && existsSync(MODEL_PATH)
+  // CLI fallback/HQ semantics are always anchored to the immutable Turbo
+  // weights. A Max live selection must never silently rewrite the HQ fallback.
+  cliAvailable = existsSync(WHISPER_CLI) && existsSync(WHISPER_TURBO_MODEL_PATH)
   if (cliAvailable) {
     console.log(`[whisper-local] whisper-cli available at ${WHISPER_CLI}`)
   }
@@ -441,7 +499,7 @@ export async function startWhisperServer(): Promise<void> {
 }
 
 async function startWhisperServerAttempt(preflightCompleted = false): Promise<void> {
-  if (!existsSync(WHISPER_SERVER) || !existsSync(MODEL_PATH)) {
+  if (!existsSync(WHISPER_SERVER) || !existsSync(COMMIT_MODEL_PATH)) {
     serverStartupState = 'unavailable'
     serverLastError = 'whisper-server or model not found'
     console.log('[whisper-local] whisper-server or model not found — using CLI fallback')
@@ -461,8 +519,8 @@ async function startWhisperServerAttempt(preflightCompleted = false): Promise<vo
   // 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).
   const serverArgs = [
-    '-m', MODEL_PATH,
-    '-t', '16',           // M3 Ultra has 24P+8E cores — 16 threads for short audio chunks
+    '-m', COMMIT_MODEL_PATH,
+    '-t', '16',           // Metal runs the encoder; measured 4/8/16-thread results favor keeping 16 across Apple silicon.
     '-l', 'en',
     '-fa',                // Flash attention — faster self-attention on Apple Silicon
     '--no-speech-thold', '0.7',  // Reject silence more aggressively (default 0.6)
@@ -599,7 +657,7 @@ export function getWhisperHealth(): {
 } {
   return {
     server: serverAvailable,
-    serverConfigured: existsSync(WHISPER_SERVER) && existsSync(MODEL_PATH),
+    serverConfigured: existsSync(WHISPER_SERVER) && existsSync(COMMIT_MODEL_PATH),
     cli: cliAvailable,
     consecutiveFailures: serverConsecutiveFailures,
     restarting: serverRestarting || serverStarting,
@@ -610,6 +668,38 @@ export function getWhisperHealth(): {
   }
 }
 
+/** Path-free truth for Control and companion capability rendering. The
+ * requested preset may degrade to Turbo when Large-v3 weights are absent, but
+ * the process never reports Max as effective unless the resident worker is
+ * actually using Large-v3. */
+export function getWhisperCommitCapability(): WhisperCommitCapability {
+  const turboPresent = existsSync(WHISPER_TURBO_MODEL_PATH)
+  const largePresent = existsSync(WHISPER_LARGE_V3_MODEL_PATH)
+  const configured = existsSync(WHISPER_SERVER) && existsSync(COMMIT_MODEL_PATH)
+  const requestedTier: WhisperTranscriptionTier = COMMIT_REQUEST === 'large-v3'
+    ? 'max'
+    : REQUESTED_TRANSCRIPTION_TIER
+  const effectiveTier: WhisperTranscriptionTier = COMMIT_MODEL === 'large-v3' ? 'max' : 'balanced'
+  const reason = COMMIT_REQUEST === 'large-v3' && !largePresent
+    ? 'large_v3_model_missing' as const
+    // Turbo is the immutable recovery model even when Max is active. Missing
+    // fallback weights are therefore degraded health, not a clean Max state.
+    : !turboPresent
+      ? 'turbo_model_missing' as const
+      : null
+  return {
+    requestedTier,
+    effectiveTier,
+    requestedModel: COMMIT_REQUEST,
+    effectiveModel: COMMIT_MODEL,
+    ready: serverAvailable,
+    configured,
+    degraded: requestedTier !== effectiveTier || reason !== null,
+    reason,
+    promptPolicy: 'full-vocabulary',
+  }
+}
+
 /** Public, path-free truth about whether an HQ request can actually run the
  * full large-v3 decoder. Keep this separate from generic Whisper liveness: the
  * persistent turbo server may be healthy while HQ weights or the CLI are not. */
@@ -931,13 +1021,23 @@ function buildPrompt(context?: string, isQuiet?: boolean): string {
  * which can receive a null C string after VAD returns no speech and crash the
  * native server before an HTTP response exists.
  */
-async function transcribeViaServer(audioBuffer: Buffer, context?: string, isQuiet?: boolean): Promise<{ text: string; words?: WhisperWord[] }> {
+async function transcribeViaServer(
+  audioBuffer: Buffer,
+  context?: string,
+  isQuiet?: boolean,
+  promptPolicy: 'full-vocabulary' | 'none' = 'full-vocabulary',
+): Promise<{ text: string; words?: WhisperWord[] }> {
   const formData = new FormData()
   // Convert Buffer to Uint8Array to satisfy Blob's BlobPart type constraint
   const blob = new Blob([new Uint8Array(audioBuffer)], { type: 'audio/wav' })
   formData.append('file', blob, 'recording.wav')
   formData.append('response_format', 'json')
-  formData.append('prompt', buildPrompt(context, isQuiet))
+  // Cosmetic preview decodes must not receive decoder bias. Omitting the field
+  // (instead of sending an empty string) keeps the wire contract unambiguous
+  // and lets diagnostics truthfully report promptPolicy: "none".
+  if (promptPolicy === 'full-vocabulary') {
+    formData.append('prompt', buildPrompt(context, isQuiet))
+  }
   // Anti-hallucination handled by client-side filter + context filtering.
   // Whisper-level entropy/logprob thresholds were too aggressive — silently dropped
   // legitimate speech from quiet sources (laptop speakers through G2 mic).
@@ -972,7 +1072,7 @@ async function transcribeViaCLI(audioBuffer: Buffer, context?: string, isQuiet?:
 
     return await new Promise<string>((resolve, reject) => {
       const proc = spawn(WHISPER_CLI, [
-        '-m', MODEL_PATH,
+        '-m', WHISPER_TURBO_MODEL_PATH,
         '-f', tmpWav,
         '-t', '12',
         '-l', 'en',
@@ -1080,7 +1180,10 @@ export async function transcribeLocal(
   audioBuffer: Buffer,
   context?: string,
   isQuiet?: boolean,
-  opts?: { affectsCircuit?: boolean },
+  opts?: {
+    affectsCircuit?: boolean
+    promptPolicy?: 'full-vocabulary' | 'none'
+  },
 ): Promise<{ text: string; backend: 'server' | 'cli'; words?: WhisperWord[] }> {
   const start = Date.now()
   const affectsCircuit = opts?.affectsCircuit !== false
@@ -1096,7 +1199,7 @@ export async function transcribeLocal(
   // Try whisper-server first (fastest: ~50-100ms, includes DTW word timestamps)
   if (serverAvailable) {
     try {
-      const result = await transcribeViaServer(audioBuffer, context, isQuiet)
+      const result = await transcribeViaServer(audioBuffer, context, isQuiet, opts?.promptPolicy)
       const text = applyCorrections(result.text)
       const words = result.words?.map(w => ({ ...w, word: applyCorrections(w.word) }))
       const elapsed = Date.now() - start

package/server/lib/whisper-preview.ts

@@ -1,19 +1,24 @@
-// Adaptive provisional transcription. This sidecar is deliberately isolated
-// from the authoritative large-v3-turbo server in whisper-local.ts:
-//   small.en  -> cosmetic prompt preview only
-//   turbo     -> committed live transcript (unchanged)
-//   large-v3  -> HQ save/polish (unchanged)
+// Adaptive provisional transcription:
+//   Balanced -> isolated Small.en cosmetic preview + Turbo live commit
+//   Max      -> resident Large-v3 worker reused for preview + live commit
+//   polish   -> Large-v3 save pass (unchanged)
 
-import { spawn } from 'node:child_process'
+import { execFile, spawn } from 'node:child_process'
 import type { ChildProcess } from 'node:child_process'
 import { existsSync } from 'node:fs'
 import { homedir } from 'node:os'
-import { join } from 'node:path'
-import { applyCorrections, getWhisperHealth, transcribeLocal } from './whisper-local.js'
-import { getOwnerName, getVocabulary } from './profile.js'
+import { basename, join } from 'node:path'
+import {
+  applyCorrections,
+  getWhisperCommitCapability,
+  getWhisperHealth,
+  transcribeLocal,
+  type WhisperCommitModel,
+  type WhisperTranscriptionTier,
+} from './whisper-local.js'
 
 export type WhisperPreviewRequest = 'auto' | 'small.en' | 'turbo' | 'off'
-export type WhisperPreviewModel = 'small.en' | 'large-v3-turbo' | null
+export type WhisperPreviewModel = 'small.en' | WhisperCommitModel | null
 export type WhisperPreviewReason =
   | 'disabled'
   | 'small_model_missing'
@@ -22,6 +27,8 @@ export type WhisperPreviewReason =
   | 'preview_start_failed'
   | 'preview_sidecar_unavailable'
   | 'turbo_unavailable'
+  | 'large_v3_model_missing'
+  | 'turbo_model_missing'
   | null
 
 export interface WhisperPreviewCapability {
@@ -31,7 +38,14 @@ export interface WhisperPreviewCapability {
   backend: 'whisper-preview-server' | 'whisper-server' | null
   degraded: boolean
   reason: WhisperPreviewReason
-  committedModel: 'large-v3-turbo'
+  previewDegraded: boolean
+  commitDegraded: boolean
+  commitReason: 'large_v3_model_missing' | 'turbo_model_missing' | null
+  committedModel: WhisperCommitModel
+  requestedCommitModel: 'turbo' | 'large-v3'
+  requestedTier: WhisperTranscriptionTier
+  effectiveTier: WhisperTranscriptionTier
+  promptPolicy: 'none'
 }
 
 const MODEL_DIR = join(process.env.HOME ?? homedir(), '.local/share/whisper-models')
@@ -42,6 +56,8 @@ const WHISPER_SERVER = ['/opt/homebrew/bin/whisper-server', '/usr/local/bin/whis
   .find(existsSync) ?? '/opt/homebrew/bin/whisper-server'
 const PREVIEW_PORT = 8177
 const PREVIEW_URL = `http://127.0.0.1:${PREVIEW_PORT}`
+const PROCESS_PROBE_TIMEOUT_MS = 2_000
+const LSOF_BIN = existsSync('/usr/sbin/lsof') ? '/usr/sbin/lsof' : 'lsof'
 
 let previewProcess: ChildProcess | null = null
 let previewAvailable = false
@@ -49,6 +65,79 @@ let previewStarting = false
 let previewFailure: WhisperPreviewReason = null
 let warnedInvalidChoice = false
 
+interface ProcessEntry {
+  pid: number
+  ppid: number
+  command: string
+}
+
+function runProcessProbe(file: string, args: string[]): Promise<string> {
+  return new Promise((resolve, reject) => {
+    execFile(file, args, {
+      encoding: 'utf8', timeout: PROCESS_PROBE_TIMEOUT_MS,
+      maxBuffer: 1024 * 1024, killSignal: 'SIGKILL',
+    }, (error, stdout) => error ? reject(error) : resolve(String(stdout)))
+  })
+}
+
+async function previewListeningPids(): Promise<number[]> {
+  try {
+    const output = await runProcessProbe(LSOF_BIN, ['-nP', `-iTCP:${PREVIEW_PORT}`, '-sTCP:LISTEN', '-t'])
+    return output.split(/\s+/).map(Number).filter(pid => Number.isInteger(pid) && pid > 0)
+  } catch (error: any) {
+    if (error?.code === 1 || error?.status === 1) return []
+    throw new Error(`unable to inspect preview port ${PREVIEW_PORT}`)
+  }
+}
+
+async function listProcesses(): Promise<ProcessEntry[]> {
+  const output = await runProcessProbe('/bin/ps', ['-axww', '-o', 'pid=,ppid=,command='])
+  return output.split('\n').flatMap(line => {
+    const match = line.match(/^\s*(\d+)\s+(\d+)\s+(.+?)\s*$/)
+    return match ? [{ pid: Number(match[1]), ppid: Number(match[2]), command: match[3] }] : []
+  })
+}
+
+function isCosPreviewCommand(command: string): boolean {
+  const firstToken = command.trim().match(/^(?:"([^"]+)"|'([^']+)'|(\S+))/)
+  const executablePath = firstToken?.[1] ?? firstToken?.[2] ?? firstToken?.[3] ?? ''
+  return basename(executablePath) === 'whisper-server'
+    && new RegExp(`(?:^|\\s)--port(?:=|\\s+)${PREVIEW_PORT}(?:\\s|$)`).test(command)
+    && command.includes(WHISPER_SMALL_EN_MODEL_PATH)
+}
+
+/** Reap only a listener proven to be our exact Small.en/8177 command. An
+ * unrelated local service is never contacted with audio or terminated. */
+async function reclaimPreviewPort(): Promise<'clear' | 'reaped' | 'foreign'> {
+  const listeners = await previewListeningPids()
+  if (listeners.length === 0) return 'clear'
+  const processes = await listProcesses()
+  const byPid = new Map(processes.map(entry => [entry.pid, entry]))
+  if (!listeners.every(pid => isCosPreviewCommand(byPid.get(pid)?.command ?? ''))) return 'foreign'
+
+  const targets = new Set(listeners)
+  let changed = true
+  while (changed) {
+    changed = false
+    for (const entry of processes) {
+      if (!targets.has(entry.pid) && targets.has(entry.ppid)) {
+        targets.add(entry.pid)
+        changed = true
+      }
+    }
+  }
+  for (const pid of [...targets].reverse()) {
+    try { process.kill(pid, 'SIGKILL') } catch (error: any) {
+      if (error?.code !== 'ESRCH') throw error
+    }
+  }
+  for (let attempt = 0; attempt < 20; attempt++) {
+    if ((await previewListeningPids()).length === 0) return 'reaped'
+    await new Promise(resolve => setTimeout(resolve, 100))
+  }
+  throw new Error(`verified Small.en worker still owns port ${PREVIEW_PORT}`)
+}
+
 export function normalizeWhisperPreviewRequest(raw?: string): WhisperPreviewRequest {
   const value = raw?.trim().toLowerCase()
   // Backward compatibility is deliberate: simply updating the server keeps
@@ -64,6 +153,11 @@ export function normalizeWhisperPreviewRequest(raw?: string): WhisperPreviewRequ
 function requestedPreviewModel(): WhisperPreviewRequest {
   const raw = process.env.COS_WHISPER_PREVIEW_MODEL
     ?? process.env.COS_WHISPER_REALTIME_MODEL // migration alias for early private installs
+  if (!raw && process.env.COS_WHISPER_TRANSCRIPTION_TIER) {
+    return process.env.COS_WHISPER_TRANSCRIPTION_TIER.trim().toLowerCase() === 'max'
+      ? 'turbo'
+      : 'small.en'
+  }
   const normalized = normalizeWhisperPreviewRequest(raw)
   if (raw && normalized === 'auto' && !['auto', 'adaptive'].includes(raw.trim().toLowerCase()) && !warnedInvalidChoice) {
     warnedInvalidChoice = true
@@ -74,17 +168,24 @@ function requestedPreviewModel(): WhisperPreviewRequest {
 
 function selectedPreviewModel(requested = requestedPreviewModel()): WhisperPreviewModel {
   if (requested === 'off') return null
-  if (requested === 'turbo') return 'large-v3-turbo'
-  if (requested === 'small.en') return existsSync(WHISPER_SMALL_EN_MODEL_PATH) ? 'small.en' : 'large-v3-turbo'
-  return existsSync(WHISPER_SMALL_EN_MODEL_PATH) ? 'small.en' : 'large-v3-turbo'
+  const primary = getWhisperCommitCapability().effectiveModel
+  if (requested === 'turbo') return primary
+  if (requested === 'small.en') return existsSync(WHISPER_SMALL_EN_MODEL_PATH) ? 'small.en' : primary
+  return existsSync(WHISPER_SMALL_EN_MODEL_PATH) ? 'small.en' : primary
 }
 
 export function getWhisperPreviewCapability(): WhisperPreviewCapability {
+  const commit = getWhisperCommitCapability()
   const requested = requestedPreviewModel()
   if (requested === 'off') {
     return {
       requested, effectiveModel: null, ready: false, backend: null,
-      degraded: false, reason: 'disabled', committedModel: 'large-v3-turbo',
+      degraded: commit.degraded, reason: commit.reason ?? 'disabled',
+      previewDegraded: false, commitDegraded: commit.degraded, commitReason: commit.reason,
+      committedModel: commit.effectiveModel,
+      requestedCommitModel: commit.requestedModel,
+      requestedTier: commit.requestedTier, effectiveTier: commit.effectiveTier,
+      promptPolicy: 'none',
     }
   }
 
@@ -94,25 +195,39 @@ export function getWhisperPreviewCapability(): WhisperPreviewCapability {
   if (selected === 'small.en' && previewAvailable) {
     return {
       requested, effectiveModel: 'small.en', ready: true,
-      backend: 'whisper-preview-server', degraded: false, reason: null,
-      committedModel: 'large-v3-turbo',
+      backend: 'whisper-preview-server', degraded: commit.degraded, reason: commit.reason,
+      previewDegraded: false, commitDegraded: commit.degraded, commitReason: commit.reason,
+      committedModel: commit.effectiveModel,
+      requestedCommitModel: commit.requestedModel,
+      requestedTier: commit.requestedTier, effectiveTier: commit.effectiveTier,
+      promptPolicy: 'none',
     }
   }
 
   const smallWasExpected = requested === 'small.en' || (requested === 'auto' && smallPresent)
-  const reason: WhisperPreviewReason = requested === 'small.en' && !smallPresent
+  const previewDegraded = smallWasExpected
+  const reason: WhisperPreviewReason = commit.reason
+    ? commit.reason
+    : requested === 'small.en' && !smallPresent
     ? 'small_model_missing'
     : smallWasExpected
       ? (previewFailure ?? (previewStarting ? null : 'preview_sidecar_unavailable'))
       : turboReady ? null : 'turbo_unavailable'
   return {
     requested,
-    effectiveModel: turboReady ? 'large-v3-turbo' : selected,
+    effectiveModel: turboReady ? commit.effectiveModel : selected,
     ready: turboReady,
     backend: turboReady ? 'whisper-server' : null,
-    degraded: smallWasExpected,
+    degraded: previewDegraded || commit.degraded,
     reason,
-    committedModel: 'large-v3-turbo',
+    previewDegraded,
+    commitDegraded: commit.degraded,
+    commitReason: commit.reason,
+    committedModel: commit.effectiveModel,
+    requestedCommitModel: commit.requestedModel,
+    requestedTier: commit.requestedTier,
+    effectiveTier: commit.effectiveTier,
+    promptPolicy: 'none',
   }
 }
 
@@ -138,12 +253,19 @@ export async function startWhisperPreviewServer(): Promise<void> {
   previewFailure = null
   try {
     try {
-      const occupied = await endpointReady('/health')
-      if (occupied.ok) {
+      const portState = await reclaimPreviewPort()
+      if (portState === 'foreign') {
         previewFailure = 'preview_port_busy'
         return
       }
-    } catch { /* clear port is expected */ }
+      if (portState === 'reaped') {
+        console.log('[whisper-preview] reaped a stale Small.en worker before restart')
+      }
+    } catch (error) {
+      previewFailure = 'preview_start_failed'
+      console.warn(`[whisper-preview] port preflight failed: ${error instanceof Error ? error.message : error}`)
+      return
+    }
 
     const args = [
       '-m', WHISPER_SMALL_EN_MODEL_PATH,
@@ -192,28 +314,44 @@ export async function startWhisperPreviewServer(): Promise<void> {
   }
 }
 
-export function stopWhisperPreviewServer(): void {
+function waitForPreviewClose(child: ChildProcess, timeoutMs: number): Promise<boolean> {
+  if (child.exitCode !== null || child.signalCode !== null) return Promise.resolve(true)
+  return new Promise(resolve => {
+    let settled = false
+    const finish = (closed: boolean) => {
+      if (settled) return
+      settled = true
+      clearTimeout(timeout)
+      child.off('close', onClose)
+      resolve(closed)
+    }
+    const onClose = () => finish(true)
+    const timeout = setTimeout(() => finish(false), timeoutMs)
+    child.once('close', onClose)
+  })
+}
+
+export async function stopWhisperPreviewServer(): Promise<void> {
   const child = previewProcess
   previewProcess = null
   previewAvailable = false
   previewStarting = false
   if (child) {
     try { child.kill('SIGTERM') } catch { /* already exited */ }
+    if (!await waitForPreviewClose(child, 2_000)) {
+      try { child.kill('SIGKILL') } catch { /* already exited */ }
+      await waitForPreviewClose(child, 1_000)
+    }
   }
 }
 
-function previewPrompt(): string {
-  const vocabulary = getVocabulary()
-  return vocabulary.length > 0
-    ? [getOwnerName(), ...vocabulary].join(', ')
-    : `${getOwnerName()}. COS Glasses. Even G2.`
-}
-
 async function transcribeViaPreviewServer(audioBuffer: Buffer): Promise<string> {
   const formData = new FormData()
   formData.append('file', new Blob([new Uint8Array(audioBuffer)], { type: 'audio/wav' }), 'recording.wav')
   formData.append('response_format', 'json')
-  formData.append('prompt', previewPrompt())
+  // Preview text is cosmetic and the same audio is authoritatively decoded by
+  // the commit lane. Small.en is disproportionately suggestible on short
+  // windows, so never bias this provisional decode with profile vocabulary.
   formData.append('suppress_non_speech', 'true')
   const response = await endpointReady('/inference', { method: 'POST', body: formData }, 5_000)
   if (!response.ok) throw new Error(`preview server ${response.status}`)
@@ -226,7 +364,7 @@ async function transcribeViaPreviewServer(audioBuffer: Buffer): Promise<string>
  * non-circuit Turbo decode and can never write committed transcript state. */
 export async function transcribeWhisperPreview(audioBuffer: Buffer): Promise<{
   text: string
-  model: 'small.en' | 'large-v3-turbo'
+  model: 'small.en' | WhisperCommitModel
   backend: 'whisper-preview-server' | 'whisper-server'
 }> {
   if (previewAvailable) {
@@ -238,6 +376,9 @@ export async function transcribeWhisperPreview(audioBuffer: Buffer): Promise<{
       console.warn(`[whisper-preview] small.en preview failed; falling back to Turbo: ${error instanceof Error ? error.message : error}`)
     }
   }
-  const result = await transcribeLocal(audioBuffer, undefined, undefined, { affectsCircuit: false })
-  return { text: result.text, model: 'large-v3-turbo', backend: 'whisper-server' }
+  const result = await transcribeLocal(audioBuffer, undefined, undefined, {
+    affectsCircuit: false,
+    promptPolicy: 'none',
+  })
+  return { text: result.text, model: getWhisperCommitCapability().effectiveModel, backend: 'whisper-server' }
 }