@gotcos/glasses-server 6.19.0 → 6.20.0

package/.cos-profile.example.json

@@ -1,7 +1,7 @@
 {
-  "owner_name": "Your Name",
+  "owner_name": "User",
   "owner_speaker_label": "Me",
-  "vocabulary": ["NameOne", "NameTwo", "YourCompany", "ProductName"],
-  "whisper_corrections": "{\"Soundalike\": \"YourName\"}",
+  "vocabulary": [],
+  "whisper_corrections": "{}",
   "negative_rules": []
 }

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
+# 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
+# been provisioned, otherwise Turbo. Guided Setup writes small.en explicitly
+# and downloads its ~466 MB model. `off` hides provisional peeks without
+# changing committed transcription or meeting audio.
+# COS_WHISPER_PREVIEW_MODEL=auto    # auto | small.en | turbo | off
 
 # Spoken reply playback defaults to local Kokoro on Apple silicon Macs. The
 # first run creates a private venv and downloads the model. Local mode fails

package/CHANGELOG.md

@@ -1,3 +1,40 @@
+## 6.20.0
+
+Adaptive transcription makes fast feedback additive instead of a quality
+trade-off. The preview lane can be fast without changing the transcript that is
+saved, searched, or sent.
+
+- **Three explicit local transcription lanes.** Prompt previews can run on a
+  dedicated Small.en sidecar, committed live text remains on
+  Large-v3-Turbo, and HQ polish remains on Large-v3. The existing phone
+  `provisional` contract is unchanged. A late or failed preview cannot replace
+  committed text or advance the recovery ledger.
+- **Safe adaptive fallback.** `COS_WHISPER_PREVIEW_MODEL` accepts `auto`,
+  `small.en`, `turbo`, or `off`. `auto` uses Small.en only when provisioned;
+  otherwise it preserves the prior Turbo behavior. A Small.en failure falls
+  back to the non-circuit Turbo path and cannot trip or success-reset the
+  authoritative Whisper breaker. The early private
+  `COS_WHISPER_REALTIME_MODEL` name remains a migration alias.
+- **No surprise on update.** An unset preview setting keeps the pre-6.20 Turbo
+  behavior. Guided Setup explicitly opts users into Small.en after provisioning
+  its weights.
+- **One setup command.** `--setup-transcription` records the adaptive choice
+  and provisions Small.en preview, Turbo commit, and Large-v3 HQ weights.
+  Pair with `--prepare-only` for COS Control so provisioning exits before the
+  managed LaunchAgent takes ownership.
+- **Truthful health.** `/api/health` and `/api/models` add path-free
+  `capabilities.transcription.live` and `.profile` blocks alongside the
+  existing `.hq` block. COS Control can report the effective preview, commit,
+  and HQ models independently.
+- **Factory vocabulary can no longer reduce accuracy.** The shipped profile is
+  empty and safe. Existing `Your Name`, `NameOne`, `NameTwo`, `YourCompany`,
+  `ProductName`, and `Soundalike -> YourName` examples are ignored everywhere
+  decoder bias or correction data is consumed. Startup warns once, and health
+  reports the ignored count. Real terms are trimmed and deduplicated.
+- **Correction keys are literal.** User correction keys are escaped before
+  regular-expression construction, so punctuation in names cannot alter the
+  matcher.
+
 ## 6.19.0
 
 Meeting audio is evidence. This release stops the server from ever deleting an

package/README.md

@@ -174,6 +174,9 @@ in the managed CLI working directory),
 server-owned query recovery), and `COS_MEDIA_ROOT` (optional image-store
 location; default `~/.cos-glasses/data/media`). Your name + transcription vocabulary live in
 `~/.cos-glasses/.cos-profile.json` (see `.cos-profile.example.json`).
+Factory example values are ignored; add the real names, companies, acronyms,
+and specialist terms you say often. Guided Setup writes a safe empty profile
+instead of biasing Whisper toward placeholder text.
 Telegram activity export is disabled by default even when a private COS
 pipeline contains `.telegram_config.json`; enable it only with the explicit
 `COS_TELEGRAM_NOTIFICATIONS=1` opt-in.
@@ -233,6 +236,20 @@ 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:
+
+```bash
+npx --yes @gotcos/glasses-server@latest --setup-transcription
+```
+
+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.
+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.
+
 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

@@ -15,6 +15,8 @@ const {
   unlinkSync,
   renameSync,
   chmodSync,
+  writeFileSync,
+  statfsSync,
 } = require('fs')
 const { delimiter, join, resolve } = require('path')
 const { homedir } = require('os')
@@ -22,6 +24,8 @@ const { homedir } = require('os')
 // bin/cli.cjs -> package root is one level up. The server lives at <root>/server.
 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')
 
 // 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
@@ -41,6 +45,7 @@ if (process.argv.includes('--help') || process.argv.includes('-h')) {
   console.log('')
   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 --prepare-only')
   console.log('')
   console.log('  Requirements:')
@@ -261,7 +266,7 @@ try {
 // and the packaged runtime without creating COS config, downloading Kokoro
 // models, installing Kokoro packages, changing COS permissions, or starting a
 // listener. An invoked agent CLI may still maintain its own user cache.
-if (process.argv.includes('--prepare-only')) {
+if (PREPARE_ONLY && !SETUP_TRANSCRIPTION) {
   if (process.platform === 'darwin' && process.arch === 'arm64') {
     const python = compatibleKokoroPython()
     if (python) {
@@ -329,6 +334,31 @@ if (existsSync(ENV_FILE)) {
     }
   } catch { /* config is optional */ }
 }
+
+function upsertEnvValue(file, key, value) {
+  const current = existsSync(file) ? readFileSync(file, 'utf8') : ''
+  const lines = current.split(/\r?\n/)
+  const prefix = `${key}=`
+  let replaced = false
+  const next = lines.map((line) => {
+    if (line.trimStart().startsWith('#')) return line
+    if (!line.startsWith(prefix)) return line
+    replaced = true
+    return `${prefix}${value}`
+  })
+  if (!replaced) {
+    if (next.length && next.at(-1) !== '') next.push('')
+    next.push(`${prefix}${value}`)
+  }
+  writeFileSync(file, next.join('\n').replace(/\n*$/, '\n'), { mode: 0o600 })
+  chmodSync(file, 0o600)
+}
+
+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'))
+}
 // Persistent profile (identity + transcription vocabulary)
 const PROFILE_FILE = join(CONFIG_DIR, '.cos-profile.json')
 const PROFILE_EXAMPLE = join(PKG_ROOT, '.cos-profile.example.json')
@@ -349,11 +379,23 @@ if (!process.env.COS_PROFILE_PATH) process.env.COS_PROFILE_PATH = PROFILE_FILE
 // 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_SERVER_KNOWN_PATHS = ['/opt/homebrew/bin/whisper-server', '/usr/local/bin/whisper-server']
 const WHISPER_MODEL_DIR = join(homedir(), '.local/share/whisper-models')
 const WHISPER_MODEL_PATH = join(WHISPER_MODEL_DIR, 'ggml-large-v3-turbo.bin')
 const WHISPER_MODEL_PARTIAL = WHISPER_MODEL_PATH + '.partial'
 const WHISPER_MODEL_URL = 'https://huggingface.co/ggerganov/whisper.cpp/resolve/main/ggml-large-v3-turbo.bin'
 const WHISPER_MODEL_MIN_BYTES = 800_000_000
+const WHISPER_SMALL_MODEL_PATH = join(WHISPER_MODEL_DIR, 'ggml-small.en.bin')
+const WHISPER_SMALL_MODEL_PARTIAL = WHISPER_SMALL_MODEL_PATH + '.partial'
+const WHISPER_SMALL_MODEL_URL = 'https://huggingface.co/ggerganov/whisper.cpp/resolve/main/ggml-small.en.bin'
+const WHISPER_SMALL_MODEL_MIN_BYTES = 400_000_000
+const WHISPER_LARGE_MODEL_PATH = join(WHISPER_MODEL_DIR, 'ggml-large-v3.bin')
+const WHISPER_LARGE_MODEL_PARTIAL = WHISPER_LARGE_MODEL_PATH + '.partial'
+const WHISPER_LARGE_MODEL_URL = 'https://huggingface.co/ggerganov/whisper.cpp/resolve/main/ggml-large-v3.bin'
+const WHISPER_LARGE_MODEL_MIN_BYTES = 2_800_000_000
+const WHISPER_MODEL_EXPECTED_BYTES = 1_620_000_000
+const WHISPER_SMALL_MODEL_EXPECTED_BYTES = 466_000_000
+const WHISPER_LARGE_MODEL_EXPECTED_BYTES = 3_100_000_000
 function findWhisperCli() {
   for (const p of WHISPER_KNOWN_PATHS) { if (existsSync(p)) return p }
   try {
@@ -363,12 +405,58 @@ function findWhisperCli() {
     return null
   }
 }
-function isValidWhisperModel(p) {
+function findWhisperServer() {
+  for (const p of WHISPER_SERVER_KNOWN_PATHS) { if (existsSync(p)) return p }
+  try {
+    const found = execSync('command -v whisper-server 2>/dev/null', { shell: '/bin/sh', stdio: 'pipe', timeout: 2000 }).toString().trim()
+    return found || null
+  } catch {
+    return null
+  }
+}
+function isValidWhisperModel(p, minBytes = WHISPER_MODEL_MIN_BYTES) {
   if (!existsSync(p)) return false
-  try { return statSync(p).size >= WHISPER_MODEL_MIN_BYTES } catch { return false }
+  try { return statSync(p).size >= minBytes } catch { return false }
 }
 const whisperCliPath = findWhisperCli()
+const whisperServerPath = findWhisperServer()
 const hasValidModel = isValidWhisperModel(WHISPER_MODEL_PATH)
+
+if (SETUP_TRANSCRIPTION && (!whisperCliPath || !whisperServerPath)) {
+  console.log('')
+  console.log(red('  ✗ Adaptive transcription 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('')
+  process.exit(1)
+}
+
+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],
+    [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]) =>
+    sum + (isValidWhisperModel(path, minimum) ? 0 : expected), 0)
+  const reclaimableBytes = targets.reduce((sum, [, partial]) => {
+    try { return sum + statSync(partial).size } catch { return sum }
+  }, 0)
+  const fsStats = statfsSync(WHISPER_MODEL_DIR)
+  const availableBytes = (fsStats.bavail * fsStats.bsize) + reclaimableBytes
+  const safetyMarginBytes = 750_000_000
+  if (missingBytes > 0 && availableBytes < missingBytes + safetyMarginBytes) {
+    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(`    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('')
+    process.exit(1)
+  }
+}
 let localVoiceReady = Boolean(whisperCliPath && hasValidModel)
 if (whisperCliPath && hasValidModel) {
   console.log(green('  ✓') + ' whisper.cpp + model ready ' + dim('— voice = local (FREE)'))
@@ -383,7 +471,7 @@ if (whisperCliPath && hasValidModel) {
   } else {
     try {
       mkdirSync(WHISPER_MODEL_DIR, { recursive: true })
-      execSync(`curl -fL --progress-bar "${WHISPER_MODEL_URL}" -o "${WHISPER_MODEL_PARTIAL}"`, { stdio: 'inherit', timeout: 900000 })
+      execFileSync('curl', ['-fL', '--progress-bar', WHISPER_MODEL_URL, '-o', WHISPER_MODEL_PARTIAL], { stdio: 'inherit', timeout: 900000 })
       const stats = statSync(WHISPER_MODEL_PARTIAL)
       if (stats.size < WHISPER_MODEL_MIN_BYTES) throw new Error(`Downloaded file too small: ${stats.size} bytes`)
       renameSync(WHISPER_MODEL_PARTIAL, WHISPER_MODEL_PATH)
@@ -405,6 +493,70 @@ if (process.env.COS_OPENAI_WHISPER_FALLBACK === '1') {
   console.log(green('  ✓') + ' Transcription policy: local-only ' + dim('— a key alone never uploads audio'))
 }
 
+const previewChoice = (process.env.COS_WHISPER_PREVIEW_MODEL || process.env.COS_WHISPER_REALTIME_MODEL || 'auto').trim().toLowerCase()
+const wantsSmallPreview = ['small', 'small.en', 'ggml-small.en.bin'].includes(previewChoice)
+if (whisperCliPath && wantsSmallPreview) {
+  if (isValidWhisperModel(WHISPER_SMALL_MODEL_PATH, WHISPER_SMALL_MODEL_MIN_BYTES)) {
+    console.log(green('  ✓') + ' Small.en preview model ready ' + dim('— Turbo remains authoritative'))
+  } else {
+    if (existsSync(WHISPER_SMALL_MODEL_PATH)) { try { unlinkSync(WHISPER_SMALL_MODEL_PATH) } catch {} }
+    if (existsSync(WHISPER_SMALL_MODEL_PARTIAL)) { try { unlinkSync(WHISPER_SMALL_MODEL_PARTIAL) } catch {} }
+    console.log(yellow('  ⚠') + ' Adaptive preview model missing')
+    console.log('    ' + dim('Downloading ggml-small.en (~466 MB).'))
+    if (process.env.SKIP_WHISPER_DOWNLOAD === '1') {
+      console.log(yellow('  ⚠') + ' SKIP_WHISPER_DOWNLOAD=1 — previews use Turbo until Small.en is provisioned')
+    } else {
+      try {
+        mkdirSync(WHISPER_MODEL_DIR, { recursive: true })
+        execFileSync('curl', ['-fL', '--progress-bar', WHISPER_SMALL_MODEL_URL, '-o', WHISPER_SMALL_MODEL_PARTIAL], { stdio: 'inherit', timeout: 900000 })
+        const stats = statSync(WHISPER_SMALL_MODEL_PARTIAL)
+        if (stats.size < WHISPER_SMALL_MODEL_MIN_BYTES) throw new Error(`Downloaded file too small: ${stats.size} bytes`)
+        renameSync(WHISPER_SMALL_MODEL_PARTIAL, WHISPER_SMALL_MODEL_PATH)
+        console.log(green('  ✓') + ' Small.en preview model downloaded ' + dim('— Turbo commit unchanged'))
+      } catch (err) {
+        try { unlinkSync(WHISPER_SMALL_MODEL_PARTIAL) } catch {}
+        console.log(red('  ✗') + ' Small.en download failed ' + dim('— previews safely fall back to Turbo'))
+        console.log('    ' + dim('Error: ' + (err.message || err).toString().slice(0, 120)))
+      }
+    }
+  }
+}
+
+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'))
+  } else {
+    if (existsSync(WHISPER_LARGE_MODEL_PATH)) { try { unlinkSync(WHISPER_LARGE_MODEL_PATH) } catch {} }
+    if (existsSync(WHISPER_LARGE_MODEL_PARTIAL)) { try { unlinkSync(WHISPER_LARGE_MODEL_PARTIAL) } catch {} }
+    console.log(yellow('  ⚠') + ' HQ polish 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')
+    } else {
+      try {
+        mkdirSync(WHISPER_MODEL_DIR, { recursive: true })
+        execFileSync('curl', ['-fL', '--progress-bar', WHISPER_LARGE_MODEL_URL, '-o', WHISPER_LARGE_MODEL_PARTIAL], { stdio: 'inherit', timeout: 1800000 })
+        const stats = statSync(WHISPER_LARGE_MODEL_PARTIAL)
+        if (stats.size < WHISPER_LARGE_MODEL_MIN_BYTES) throw new Error(`Downloaded file too small: ${stats.size} bytes`)
+        renameSync(WHISPER_LARGE_MODEL_PARTIAL, WHISPER_LARGE_MODEL_PATH)
+        console.log(green('  ✓') + ' Large-v3 HQ model downloaded')
+      } catch (err) {
+        try { unlinkSync(WHISPER_LARGE_MODEL_PARTIAL) } catch {}
+        console.log(red('  ✗') + ' Large-v3 download failed ' + dim('— live Turbo remains available'))
+        console.log('    ' + dim('Error: ' + (err.message || err).toString().slice(0, 120)))
+      }
+    }
+  }
+}
+
+if (PREPARE_ONLY && SETUP_TRANSCRIPTION) {
+  console.log('')
+  console.log(green('  ✓ Adaptive transcription setup complete'))
+  console.log('    Return to COS Control and Restart, install, or update the managed server.')
+  console.log('')
+  process.exit(0)
+}
+
 // Step 6: image capability — ffmpeg validates, strips metadata, normalizes,
 // and builds the exact 288x144 G2 variant. It is optional so text/voice remain
 // useful on a minimal install, but the launcher should make the gap visible.

package/managed-runtime-contract.json

@@ -21,6 +21,8 @@
     "COS_LIVE_CUES_AUTO",
     "COS_BATCH_HQ_METAL",
     "COS_BATCH_HQ_FORCE_CPU",
+    "COS_WHISPER_PREVIEW_MODEL",
+    "COS_WHISPER_REALTIME_MODEL",
     "COS_UNSAVED_AUDIO_RETENTION_HOURS",
     "COS_CLAUDE_TRUST_MODE",
     "COS_CODEX_SANDBOX",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gotcos/glasses-server",
-  "version": "6.19.0",
+  "version": "6.20.0",
   "description": "COS Glasses \u2014 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

@@ -48,6 +48,7 @@ import {
   stopCodexModelCatalogRefresh,
 } from './lib/codex-model-catalog.js'
 import { startWhisperServer, stopWhisperServer } from './lib/whisper-local.js'
+import { startWhisperPreviewServer, stopWhisperPreviewServer } from './lib/whisper-preview.js'
 import { startLocalTtsServer, stopLocalTtsServer } from './lib/tts-local.js'
 import { initSileroVAD } from './lib/vad-silero.js'
 import { initSessionCache } from './lib/session-cache-writer.js'
@@ -58,6 +59,7 @@ import { listenRequiredServers, type RequiredListener } from './lib/listener-sta
 import { serverMetrics } from './lib/server-metrics.js'
 import { initializeServerInstanceId } from './lib/server-instance-id.js'
 import { appendPrivateEnvBlock, UnsafeUserConfigPathError } from './lib/secure-user-config.js'
+import { getTranscriptionProfileStatus } from './lib/profile.js'
 import { createQueryJobsRouter } from './routes/query-jobs.js'
 import {
   initQueryJobRuntime,
@@ -296,6 +298,7 @@ async function gracefulShutdown(): Promise<void> {
   try { logActiveSessionsOnShutdown() } catch { /* best-effort flush */ }
   stopCodexModelCatalogRefresh()
   stopWhisperServer()
+  stopWhisperPreviewServer()
   stopLocalTtsServer()
   clearTimeout(forceExit)
   process.exit(0)
@@ -407,7 +410,19 @@ listenRequiredServers(listeners).then(() => {
     // known-good snapshot if Codex is temporarily unavailable.
     startCodexModelCatalogRefresh()
     // Start local whisper-server (model stays in RAM for ~50ms transcription)
-    startWhisperServer().catch(err => console.error('[startup] Whisper server error:', err))
+    const transcriptionProfile = getTranscriptionProfileStatus()
+    if (transcriptionProfile.ignoredPlaceholderTerms > 0 || transcriptionProfile.ignoredPlaceholderCorrection) {
+      console.warn(
+        '[whisper] .cos-profile.json still contains factory vocabulary. ' +
+        'Placeholder terms are ignored; add real names and terminology in Guided Setup for better accuracy.',
+      )
+    }
+    // Load the authoritative Turbo worker first. Starting both model loads at
+    // once made first boot slower on smaller Macs and could cause Control's
+    // readiness proof to time out even though both models were healthy.
+    startWhisperServer()
+      .then(() => startWhisperPreviewServer())
+      .catch(err => console.error('[startup] Whisper server/preview error:', err))
     startLocalTtsServer().catch(err => console.error('[startup] Local TTS server error:', err))
     // Initialize speaker embeddings (voiceprint-based diarization) — fails soft if model absent
     const embeddingOk = initSpeakerEmbeddings()

package/server/lib/hallucination-filter.ts

@@ -11,7 +11,7 @@
 //   isFullHallucination(text) — returns true if the text IS a hallucination in its
 //     entirety (silence artifacts, caption training, foreign script, filler-only).
 
-import { getNegativeRules, getVocabulary, getOwnerName, loadProfileField } from './profile.js'
+import { getNegativeRules, getVocabulary, getOwnerName, getWhisperCorrections } from './profile.js'
 
 // ── Whole-chunk silence hallucinations ─────────────────────────────────────
 const KNOWN_HALLUCINATIONS = [
@@ -333,13 +333,10 @@ function getVocabEchoMatcher(): RegExp {
   for (const v of getVocabulary()) if (v && v.trim()) raw.add(v.trim())
   // Include whisper_corrections key/value variants so the echo matches whatever
   // spelling whisper emits ("POS Nation" ↔ "POSNation", "Jewel 360" ↔ "Jewel360").
-  try {
-    const corrRaw = loadProfileField('whisper_corrections', '')
-    if (corrRaw) {
-      const map = JSON.parse(corrRaw) as Record<string, string>
-      for (const [k, val] of Object.entries(map)) { if (k) raw.add(k); if (val) raw.add(val) }
-    }
-  } catch { /* malformed corrections — ignore */ }
+  for (const [key, value] of Object.entries(getWhisperCorrections())) {
+    raw.add(key)
+    raw.add(value)
+  }
   // Only UNAMBIGUOUS terms trigger an echo drop: multi-word phrases ("POS Nation",
   // "IT Retail", "Jeremy Sokolic") and brand-shaped single tokens with an internal
   // capital or digit ("POSNation", "CaratIQ", "Jewel360"). Plain single-word tokens

package/server/lib/profile.ts

@@ -8,6 +8,10 @@ import { atomicWriteFileSync } from './atomic-fs.js'
 
 const APP_ROOT = resolve(import.meta.dirname, '../..')
 
+const PLACEHOLDER_OWNER_NAMES = new Set(['your name', 'user'])
+const PLACEHOLDER_VOCABULARY = new Set(['nameone', 'nametwo', 'yourcompany', 'productname'])
+const PLACEHOLDER_CORRECTIONS = new Set(['soundalike\u0000yourname'])
+
 /** The profile in the data home. Survives updates; the APP_ROOT copy does not. */
 export function homeProfilePath(): string {
   return resolve(homedir(), '.cos-glasses', '.cos-profile.json')
@@ -81,7 +85,8 @@ export function loadProfileField(field: string, fallback: string): string {
 }
 
 export function getOwnerName(): string {
-  return loadProfileField('owner_name', 'User')
+  const value = loadProfileField('owner_name', 'User').trim()
+  return !value || PLACEHOLDER_OWNER_NAMES.has(value.toLowerCase()) ? 'User' : value
 }
 
 /** Short speaker label for the glasses wearer, used by diarization to fast-path
@@ -92,7 +97,81 @@ export function getOwnerSpeakerLabel(): string {
 
 export function getVocabulary(): string[] {
   const profile = loadProfile()
-  return Array.isArray(profile.vocabulary) ? profile.vocabulary as string[] : []
+  if (!Array.isArray(profile.vocabulary)) return []
+  const seen = new Set<string>()
+  return (profile.vocabulary as unknown[]).flatMap(value => {
+    if (typeof value !== 'string') return []
+    const term = value.trim()
+    const key = term.toLowerCase()
+    if (!term || PLACEHOLDER_VOCABULARY.has(key) || seen.has(key)) return []
+    seen.add(key)
+    return [term]
+  })
+}
+
+/** Typed correction map shared by every decoder caller. The legacy profile
+ * stores this field as a JSON string, while hand-authored profiles sometimes
+ * use an object; accept both and ignore the factory example pair. */
+export function getWhisperCorrections(): Record<string, string> {
+  const raw = loadProfile().whisper_corrections
+  let parsed: unknown = raw
+  if (typeof raw === 'string') {
+    try { parsed = JSON.parse(raw) } catch { return {} }
+  }
+  if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) return {}
+
+  const corrections: Record<string, string> = {}
+  for (const [sourceRaw, targetRaw] of Object.entries(parsed as Record<string, unknown>)) {
+    if (typeof targetRaw !== 'string') continue
+    const source = sourceRaw.trim()
+    const target = targetRaw.trim()
+    if (!source || !target) continue
+    if (PLACEHOLDER_CORRECTIONS.has(`${source.toLowerCase()}\u0000${target.toLowerCase()}`)) continue
+    corrections[source] = target
+  }
+  return corrections
+}
+
+export interface TranscriptionProfileStatus {
+  configured: boolean
+  ownerConfigured: boolean
+  vocabularyTerms: number
+  ignoredPlaceholderTerms: number
+  ignoredPlaceholderCorrection: boolean
+}
+
+/** Path-free setup truth for startup warnings, health, and COS Control. */
+export function getTranscriptionProfileStatus(): TranscriptionProfileStatus {
+  const profile = loadProfile()
+  const rawOwner = typeof profile.owner_name === 'string' ? profile.owner_name.trim() : ''
+  const rawVocabulary = Array.isArray(profile.vocabulary)
+    ? (profile.vocabulary as unknown[]).filter((value): value is string => typeof value === 'string')
+    : []
+  const ignoredPlaceholderTerms = rawVocabulary.filter(term => PLACEHOLDER_VOCABULARY.has(term.trim().toLowerCase())).length
+  const rawCorrections = (() => {
+    const value = profile.whisper_corrections
+    if (typeof value === 'string') {
+      try { return JSON.parse(value) as unknown } catch { return null }
+    }
+    return value
+  })()
+  const ignoredPlaceholderCorrection = Boolean(
+    rawCorrections
+      && typeof rawCorrections === 'object'
+      && !Array.isArray(rawCorrections)
+      && Object.entries(rawCorrections as Record<string, unknown>).some(([source, target]) =>
+        typeof target === 'string'
+        && PLACEHOLDER_CORRECTIONS.has(`${source.trim().toLowerCase()}\u0000${target.trim().toLowerCase()}`)),
+  )
+  const ownerConfigured = Boolean(rawOwner) && !PLACEHOLDER_OWNER_NAMES.has(rawOwner.toLowerCase())
+  const vocabularyTerms = getVocabulary().length
+  return {
+    configured: ownerConfigured || vocabularyTerms > 0 || Object.keys(getWhisperCorrections()).length > 0,
+    ownerConfigured,
+    vocabularyTerms,
+    ignoredPlaceholderTerms,
+    ignoredPlaceholderCorrection,
+  }
 }
 
 export function getSystemContext(): string {

package/server/lib/whisper-local.ts

@@ -12,7 +12,7 @@ import { writeFileSync, unlinkSync, existsSync, readFileSync } from 'node:fs'
 import { basename, join } from 'node:path'
 import { homedir } from 'node:os'
 import crypto from 'node:crypto'
-import { getVocabulary, getOwnerName } from './profile.js'
+import { getVocabulary, getOwnerName, getWhisperCorrections } from './profile.js'
 import { stripBrandUrls } from './hallucination-filter.js'
 import {
   batchHqMetalEnabled,
@@ -1022,22 +1022,15 @@ async function transcribeViaCLI(audioBuffer: Buffer, context?: string, isQuiet?:
 // Post-processing correction dictionary — deterministic fixes for names Whisper garbles.
 // Prompt biasing is probabilistic; regex replacement is guaranteed.
 // User-specific corrections loaded from .cos-profile.json "whisper_corrections" field.
-import { loadProfileField } from './profile.js'
-
 function buildCorrections(): Array<[RegExp, string]> {
   const corrections: Array<[RegExp, string]> = []
 
-  // Load user-configured corrections from profile
-  // Format: { "whisper_corrections": { "Soundalike": "YourName", ... } }
-  try {
-    const raw = loadProfileField('whisper_corrections', '')
-    if (raw) {
-      const map = JSON.parse(raw) as Record<string, string>
-      for (const [pattern, replacement] of Object.entries(map)) {
-        corrections.push([new RegExp(`\\b${pattern}\\b`, 'gi'), replacement])
-      }
-    }
-  } catch { /* invalid JSON — skip */ }
+  // Escape correction keys before interpolation. Names such as "A.C.M.E."
+  // are literal vocabulary, never regular-expression programs.
+  for (const [pattern, replacement] of Object.entries(getWhisperCorrections())) {
+    const escaped = pattern.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+    corrections.push([new RegExp(`\\b${escaped}\\b`, 'gi'), replacement])
+  }
 
   return corrections
 }

package/server/lib/whisper-preview.ts

@@ -0,0 +1,243 @@
+// 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)
+
+import { 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'
+
+export type WhisperPreviewRequest = 'auto' | 'small.en' | 'turbo' | 'off'
+export type WhisperPreviewModel = 'small.en' | 'large-v3-turbo' | null
+export type WhisperPreviewReason =
+  | 'disabled'
+  | 'small_model_missing'
+  | 'preview_binary_missing'
+  | 'preview_port_busy'
+  | 'preview_start_failed'
+  | 'preview_sidecar_unavailable'
+  | 'turbo_unavailable'
+  | null
+
+export interface WhisperPreviewCapability {
+  requested: WhisperPreviewRequest
+  effectiveModel: WhisperPreviewModel
+  ready: boolean
+  backend: 'whisper-preview-server' | 'whisper-server' | null
+  degraded: boolean
+  reason: WhisperPreviewReason
+  committedModel: 'large-v3-turbo'
+}
+
+const MODEL_DIR = join(process.env.HOME ?? homedir(), '.local/share/whisper-models')
+export const WHISPER_SMALL_EN_MODEL_PATH = join(MODEL_DIR, 'ggml-small.en.bin')
+const VAD_MODEL_PATH = join(MODEL_DIR, 'ggml-silero-v5.1.2.bin')
+const VAD_ENABLED = process.env.COS_WHISPER_VAD !== '0'
+const WHISPER_SERVER = ['/opt/homebrew/bin/whisper-server', '/usr/local/bin/whisper-server']
+  .find(existsSync) ?? '/opt/homebrew/bin/whisper-server'
+const PREVIEW_PORT = 8177
+const PREVIEW_URL = `http://127.0.0.1:${PREVIEW_PORT}`
+
+let previewProcess: ChildProcess | null = null
+let previewAvailable = false
+let previewStarting = false
+let previewFailure: WhisperPreviewReason = null
+let warnedInvalidChoice = false
+
+export function normalizeWhisperPreviewRequest(raw?: string): WhisperPreviewRequest {
+  const value = raw?.trim().toLowerCase()
+  // Backward compatibility is deliberate: simply updating the server keeps
+  // the old Turbo preview. Guided Setup opts the user into Small.en.
+  if (!value) return 'turbo'
+  if (value === 'auto' || value === 'adaptive') return 'auto'
+  if (value === 'small' || value === 'small.en' || value === 'ggml-small.en.bin') return 'small.en'
+  if (value === 'turbo' || value === 'large-v3-turbo' || value === 'ggml-large-v3-turbo.bin') return 'turbo'
+  if (value === 'off' || value === 'disabled' || value === '0') return 'off'
+  return 'auto'
+}
+
+function requestedPreviewModel(): WhisperPreviewRequest {
+  const raw = process.env.COS_WHISPER_PREVIEW_MODEL
+    ?? process.env.COS_WHISPER_REALTIME_MODEL // migration alias for early private installs
+  const normalized = normalizeWhisperPreviewRequest(raw)
+  if (raw && normalized === 'auto' && !['auto', 'adaptive'].includes(raw.trim().toLowerCase()) && !warnedInvalidChoice) {
+    warnedInvalidChoice = true
+    console.warn(`[whisper-preview] Unknown model "${raw}"; using adaptive selection.`)
+  }
+  return normalized
+}
+
+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'
+}
+
+export function getWhisperPreviewCapability(): WhisperPreviewCapability {
+  const requested = requestedPreviewModel()
+  if (requested === 'off') {
+    return {
+      requested, effectiveModel: null, ready: false, backend: null,
+      degraded: false, reason: 'disabled', committedModel: 'large-v3-turbo',
+    }
+  }
+
+  const smallPresent = existsSync(WHISPER_SMALL_EN_MODEL_PATH)
+  const selected = selectedPreviewModel(requested)
+  const turboReady = getWhisperHealth().server
+  if (selected === 'small.en' && previewAvailable) {
+    return {
+      requested, effectiveModel: 'small.en', ready: true,
+      backend: 'whisper-preview-server', degraded: false, reason: null,
+      committedModel: 'large-v3-turbo',
+    }
+  }
+
+  const smallWasExpected = requested === 'small.en' || (requested === 'auto' && smallPresent)
+  const reason: WhisperPreviewReason = 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,
+    ready: turboReady,
+    backend: turboReady ? 'whisper-server' : null,
+    degraded: smallWasExpected,
+    reason,
+    committedModel: 'large-v3-turbo',
+  }
+}
+
+async function endpointReady(path: '/health' | '/inference', init?: RequestInit, timeoutMs = 1_000): Promise<Response> {
+  return fetch(`${PREVIEW_URL}${path}`, { ...init, signal: AbortSignal.timeout(timeoutMs) })
+}
+
+/** Start the optional small.en preview worker. Failure is cosmetic: committed
+ * Turbo and every recovery/finalization path stay untouched. */
+export async function startWhisperPreviewServer(): Promise<void> {
+  const requested = requestedPreviewModel()
+  if (selectedPreviewModel(requested) !== 'small.en' || previewProcess || previewAvailable || previewStarting) return
+  if (!existsSync(WHISPER_SMALL_EN_MODEL_PATH)) {
+    previewFailure = 'small_model_missing'
+    return
+  }
+  if (!existsSync(WHISPER_SERVER)) {
+    previewFailure = 'preview_binary_missing'
+    return
+  }
+
+  previewStarting = true
+  previewFailure = null
+  try {
+    try {
+      const occupied = await endpointReady('/health')
+      if (occupied.ok) {
+        previewFailure = 'preview_port_busy'
+        return
+      }
+    } catch { /* clear port is expected */ }
+
+    const args = [
+      '-m', WHISPER_SMALL_EN_MODEL_PATH,
+      '-t', '16',
+      '-l', 'en',
+      '-fa',
+      '--no-speech-thold', '0.7',
+      '--host', '127.0.0.1',
+      '--port', String(PREVIEW_PORT),
+    ]
+    if (VAD_ENABLED && existsSync(VAD_MODEL_PATH)) {
+      args.push('--vad', '--vad-model', VAD_MODEL_PATH)
+    }
+    const child = spawn(WHISPER_SERVER, args, { stdio: 'ignore', detached: false })
+    previewProcess = child
+    child.once('close', code => {
+      if (previewProcess !== child) return
+      previewProcess = null
+      previewAvailable = false
+      previewFailure = code === 0 ? 'preview_sidecar_unavailable' : 'preview_start_failed'
+    })
+    child.once('error', () => {
+      previewAvailable = false
+      previewFailure = 'preview_start_failed'
+    })
+
+    const deadline = Date.now() + 45_000
+    while (Date.now() < deadline) {
+      if (child.exitCode !== null || child.signalCode !== null) break
+      try {
+        const response = await endpointReady('/health', undefined, 1_000)
+        if (response.ok) {
+          previewAvailable = true
+          previewFailure = null
+          console.log('[whisper-preview] small.en ready for provisional text; committed text remains Turbo')
+          return
+        }
+      } catch { /* model still loading */ }
+      await new Promise(resolve => setTimeout(resolve, 1_000))
+    }
+    try { child.kill('SIGKILL') } catch { /* already exited */ }
+    if (previewProcess === child) previewProcess = null
+    previewFailure = 'preview_start_failed'
+  } finally {
+    previewStarting = false
+  }
+}
+
+export function stopWhisperPreviewServer(): void {
+  const child = previewProcess
+  previewProcess = null
+  previewAvailable = false
+  previewStarting = false
+  if (child) {
+    try { child.kill('SIGTERM') } catch { /* already exited */ }
+  }
+}
+
+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())
+  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}`)
+  const result = await response.json() as { text?: unknown }
+  if (typeof result.text !== 'string') throw new Error('preview server returned invalid text')
+  return applyCorrections(result.text.trim())
+}
+
+/** Cosmetic preview only. A small-worker failure falls through to the existing
+ * 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'
+  backend: 'whisper-preview-server' | 'whisper-server'
+}> {
+  if (previewAvailable) {
+    try {
+      return { text: await transcribeViaPreviewServer(audioBuffer), model: 'small.en', backend: 'whisper-preview-server' }
+    } catch (error) {
+      previewAvailable = false
+      previewFailure = 'preview_sidecar_unavailable'
+      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' }
+}

package/server/routes/glossary.ts

@@ -13,7 +13,7 @@ import { errMsg } from '../lib/utils.js'
 import {
   getVocabulary,
   getNegativeRules,
-  loadProfileField,
+  getWhisperCorrections,
   updateProfileFields,
 } from '../lib/profile.js'
 import { resetDecoderCaches } from '../lib/whisper-local.js'
@@ -36,16 +36,7 @@ function looksLikeUrlEmailPath(s: string): boolean {
 }
 
 function readCorrections(): Record<string, string> {
-  try {
-    const raw = loadProfileField('whisper_corrections', '')
-    if (!raw) return {}
-    const parsed = JSON.parse(raw)
-    return (parsed && typeof parsed === 'object' && !Array.isArray(parsed))
-      ? parsed as Record<string, string>
-      : {}
-  } catch {
-    return {}
-  }
+  return getWhisperCorrections()
 }
 
 function currentGlossary() {

package/server/routes/health.ts

@@ -39,6 +39,8 @@ import { getLocalTtsHealth, refreshLocalTtsHealth } from '../lib/tts-local.js'
 import { liveCuesCapability } from '../lib/live-cues-capability.js'
 import { getMeetingSyncSnapshot } from '../lib/meeting-batch-progress.js'
 import { listUnsavedCaptures } from '../lib/unsaved-audio-quarantine.js'
+import { getWhisperPreviewCapability } from '../lib/whisper-preview.js'
+import { getTranscriptionProfileStatus } from '../lib/profile.js'
 
 export const healthRouter = Router()
 
@@ -203,6 +205,8 @@ healthRouter.get('/health', async (_req, res) => {
   const localFirstMeetings = localFirstMeetingsCapability(getServerInstanceId())
   const transcription = getTranscriptionPolicySnapshot()
   const transcriptionHq = getHighQualityTranscriptionCapability()
+  const transcriptionLive = getWhisperPreviewCapability()
+  const transcriptionProfile = getTranscriptionProfileStatus()
   const recovery = managedRuntimeCapability()
   const maintenance = maintenanceLifecycle.snapshot()
   const tts_local = getLocalTtsHealth()
@@ -293,7 +297,12 @@ healthRouter.get('/health', async (_req, res) => {
     meeting_sync,
     unsaved_captures,
     capabilities: {
-      transcription: { ...transcription, hq: transcriptionHq },
+      transcription: {
+        ...transcription,
+        live: transcriptionLive,
+        hq: transcriptionHq,
+        profile: transcriptionProfile,
+      },
       recovery,
       maintenance: {
         state: maintenance.state,
@@ -326,6 +335,8 @@ healthRouter.get('/models', async (req, res) => {
   const localFirstMeetings = localFirstMeetingsCapability(getServerInstanceId())
   const transcription = getTranscriptionPolicySnapshot()
   const transcriptionHq = getHighQualityTranscriptionCapability()
+  const transcriptionLive = getWhisperPreviewCapability()
+  const transcriptionProfile = getTranscriptionProfileStatus()
   const cursorOptions = cursorCatalog.options.filter(option => !!option.id)
   res.json({
     ...catalog,
@@ -341,7 +352,12 @@ healthRouter.get('/models', async (req, res) => {
         enabled: durableJobs.enabled,
         protocolVersion: durableJobs.protocolVersion,
       },
-      transcription: { ...transcription, hq: transcriptionHq },
+      transcription: {
+        ...transcription,
+        live: transcriptionLive,
+        hq: transcriptionHq,
+        profile: transcriptionProfile,
+      },
       cliDebug: CLI_DEBUG_CAPABILITY,
       recovery: managedRuntimeCapability(),
       // Same helper as /api/health — the companion's 15s liveness poll reads

package/server/routes/prompt-drafts.ts

@@ -34,6 +34,7 @@ import {
   applyNegativeRules,
 } from '../lib/hallucination-filter.js'
 import { applyCorrections } from '../lib/whisper-local.js'
+import { transcribeWhisperPreview } from '../lib/whisper-preview.js'
 import { autoCleanDictation, AUTOCLEAN_MAX_CHARS } from '../lib/dictation-clean.js'
 import { getVocabulary } from '../lib/profile.js'
 import { createBreaker } from '../lib/claude-circuit.js'
@@ -414,11 +415,7 @@ promptDraftsRouter.post('/prompt-drafts/:draftId/peek', async (req, res) => {
     peekTail = peekTail.then(async () => {
       lease.setPhase('active')
       try {
-        const result = await transcribeAudioBuffer(audio, {
-          mode: 'fast',
-          policy: 'local-only',
-          affectsCircuit: false,
-        })
+        const result = await transcribeWhisperPreview(audio)
         const text = sanitizeTranscript(draftId, result.text, false)
         if (!text) return
         if (!loadPromptDraftMeta(draftId)) return