@gotcos/glasses-server 6.71.14 → 6.72.0

package/server/lib/stt-settings.ts

@@ -0,0 +1,342 @@
+// Speech-to-text settings (6.72.0): which engine previews live speech, which
+// engine writes the saved meeting (HQ), which engine gives HQ a second opinion,
+// whether the resolver may use it, the ASR input front end and the quiet gate.
+//
+// Stored in <data>/stt-settings.json (atomic). Read on every use with an mtime
+// check, so a change applies without a restart: the preview, front end and
+// quiet gate from the next live chunk; HQ, second opinion and resolver from the
+// next saved meeting (an HQ job snapshots the settings when it starts and never
+// switches engines mid-job).
+//
+// Defaults and the evidence behind them: docs/stt-672-evaluation.md.
+
+import { readFileSync, statSync } from 'node:fs'
+import { atomicWriteFileSync } from './atomic-fs.js'
+import { dataPath } from './data-dir.js'
+
+export const PREVIEW_IDS = ['turbo', 'large-v3', 'parakeet', 'nemotron-560'] as const
+export const HQ_IDS = ['large-v3', 'large-v3-legacy', 'parakeet-ultra'] as const
+export const SECOND_OPINION_IDS = ['off', 'parakeet-ultra', 'large-v3'] as const
+export const FRONT_END_IDS = ['highpass', 'full'] as const
+export const QUIET_GATE_IDS = ['silero', 'rms'] as const
+
+export type PreviewId = typeof PREVIEW_IDS[number]
+export type HqId = typeof HQ_IDS[number]
+export type SecondOpinionId = typeof SECOND_OPINION_IDS[number]
+export type FrontEndId = typeof FRONT_END_IDS[number]
+export type QuietGateId = typeof QUIET_GATE_IDS[number]
+
+export interface SttSettings {
+  preview: PreviewId
+  hq: HqId
+  secondOpinion: SecondOpinionId
+  resolver: boolean
+  frontEnd: FrontEndId
+  quietGate: QuietGateId
+}
+
+/** Items 1 to 3 on. Second opinion off and the resolver off: on the shipped
+ *  path (production 30 s windows, docs/stt-672-evaluation.md) neither
+ *  resolver configuration passed the adoption rule (Large-v3 + Ultra -1.6% WER,
+ *  CI -4.7 to +1.1), so Large-v3 alone writes the meeting. Parakeet Ultra stays
+ *  installable for the preview and as the HQ primary. */
+export const DEFAULT_STT_SETTINGS: Readonly<SttSettings> = Object.freeze({
+  preview: 'turbo',
+  hq: 'large-v3',
+  secondOpinion: 'off',
+  resolver: false,
+  frontEnd: 'highpass',
+  quietGate: 'silero',
+})
+
+export const STT_SETTINGS_FILE = 'stt-settings.json'
+const settingsPath = () => dataPath(STT_SETTINGS_FILE)
+
+function pick<T extends string>(ids: readonly T[], value: unknown, fallback: T): T {
+  return typeof value === 'string' && (ids as readonly string[]).includes(value) ? value as T : fallback
+}
+
+/** Unknown or damaged stored values fall back to the default, key by key. */
+export function normalizeStoredSettings(raw: unknown): SttSettings {
+  const o = raw && typeof raw === 'object' && !Array.isArray(raw) ? raw as Record<string, unknown> : {}
+  return {
+    preview: pick(PREVIEW_IDS, o.preview, DEFAULT_STT_SETTINGS.preview),
+    hq: pick(HQ_IDS, o.hq, DEFAULT_STT_SETTINGS.hq),
+    secondOpinion: pick(SECOND_OPINION_IDS, o.secondOpinion, DEFAULT_STT_SETTINGS.secondOpinion),
+    resolver: typeof o.resolver === 'boolean' ? o.resolver : DEFAULT_STT_SETTINGS.resolver,
+    frontEnd: pick(FRONT_END_IDS, o.frontEnd, DEFAULT_STT_SETTINGS.frontEnd),
+    quietGate: pick(QUIET_GATE_IDS, o.quietGate, DEFAULT_STT_SETTINGS.quietGate),
+  }
+}
+
+let cache: { mtimeMs: number; size: number; value: SttSettings } | null = null
+let warnedCorrupt = false
+
+/** Stored settings (no capability check). Cheap enough for every live chunk. */
+export function readSttSettings(): SttSettings {
+  const path = settingsPath()
+  let stat: { mtimeMs: number; size: number } | null = null
+  try { const s = statSync(path); stat = { mtimeMs: s.mtimeMs, size: s.size } } catch { stat = null }
+  if (!stat) { cache = null; return { ...DEFAULT_STT_SETTINGS } }
+  if (cache && cache.mtimeMs === stat.mtimeMs && cache.size === stat.size) return { ...cache.value }
+  let value: SttSettings
+  try { value = normalizeStoredSettings(JSON.parse(readFileSync(path, 'utf8'))) } catch (error) {
+    // Unreadable settings run the defaults; say so once, not on every chunk.
+    if (!warnedCorrupt) { warnedCorrupt = true; console.warn(`[stt] ${STT_SETTINGS_FILE} is unreadable (${error instanceof Error ? error.message : error}); using the defaults until it is rewritten`) }
+    value = { ...DEFAULT_STT_SETTINGS }
+  }
+  cache = { ...stat, value }
+  return { ...value }
+}
+
+export function writeSttSettings(next: SttSettings): void {
+  atomicWriteFileSync(settingsPath(), JSON.stringify(next, null, 2) + '\n', { mode: 0o600 })
+  cache = null
+}
+
+export function __resetSttSettingsCacheForTests(): void { cache = null; warnedCorrupt = false }
+
+// ── Last HQ job (for GET: what actually happened, not only what was chosen) ──
+
+export interface LastSttJob {
+  at: string
+  meeting: string
+  outcome: 'batch' | 'rejected' | 'failed'
+  summary: unknown
+}
+const LAST_JOB_FILE = 'stt-last-job.json'
+
+export function recordLastSttJob(job: LastSttJob): void {
+  try { atomicWriteFileSync(dataPath(LAST_JOB_FILE), JSON.stringify(job, null, 2) + '\n', { mode: 0o600 }) } catch { /* telemetry only */ }
+}
+
+export function readLastSttJob(): LastSttJob | null {
+  try { return JSON.parse(readFileSync(dataPath(LAST_JOB_FILE), 'utf8')) as LastSttJob } catch { return null }
+}
+
+// ── Capabilities ──────────────────────────────────────────────────────────────
+
+export interface SttCapabilities {
+  turboModel: boolean
+  /** The live commit worker runs Large-v3 (the Max tier). */
+  liveLargeV3: boolean
+  /** whisper-cli plus Large-v3 weights for meeting HQ. */
+  hqLargeV3: boolean
+  parakeetInstalled: boolean
+  parakeetPreviewWarm: boolean
+  parakeetPreviewWarming: boolean
+  /** The warm-up ran and failed (distinct from still warming). */
+  parakeetPreviewWarmFailed?: boolean
+  /** Repeated preview misses opened the preview breaker: Turbo until it closes. */
+  parakeetPreviewBreakerOpen?: boolean
+  previewDisabledByEnv: boolean
+}
+
+export interface SttOption {
+  id: string
+  label: string
+  available: boolean
+  experimental: boolean
+  note: string
+}
+
+/** Every preview `model` string this server can return (contract-tested;
+ *  a subset of what phone 6.10.639 accepts). */
+export const PREVIEW_MODEL_STRINGS = ['large-v3-turbo', 'parakeet-ultra'] as const
+/** The request parameter a client uses to say which preview models it accepts. */
+export const PREVIEW_MODELS_PARAM = 'previewModels'
+export const PREVIEW_REQUIRES_APP = '6.10.639'
+
+export function previewOptions(c: SttCapabilities): SttOption[] {
+  const parakeetNote = !c.parakeetInstalled
+    ? 'Install Parakeet on this Mac first.'
+    : c.parakeetPreviewBreakerOpen
+      ? 'Parakeet missed several previews in a row; Whisper Turbo previews for a few minutes, then Parakeet is tried again.'
+      : c.parakeetPreviewWarm
+        ? 'Parakeet Ultra on the Neural Engine, about 0.3 s per chunk. Experimental: compare it live yourself. Needs COS Glasses 6.10.639; older phones keep Whisper Turbo.'
+        : c.parakeetPreviewWarmFailed
+          ? 'Parakeet could not start; Whisper Turbo previews. It is tried again every 2 minutes.'
+          : c.parakeetPreviewWarming
+            ? 'Warming up (the first load takes 15 to 25 s). Whisper Turbo previews until it is ready.'
+            : 'Warms up when selected and no recording is live. Whisper Turbo previews until it is ready.'
+  return [
+    { id: 'turbo', label: 'Whisper Turbo', available: c.turboModel && !c.previewDisabledByEnv, experimental: false,
+      note: c.previewDisabledByEnv ? 'Meeting preview is turned off on this server (COS_WHISPER_MEETING_PREVIEW=0).' : c.turboModel ? 'Fast provisional text. Saved text never comes from the preview.' : 'Turbo weights are missing on this Mac.' },
+    { id: 'large-v3', label: 'Whisper Large-v3', available: false, experimental: false,
+      note: 'Not offered: a Large-v3 preview would share the live Large-v3 worker that writes the saved text.' },
+    { id: 'parakeet', label: 'Parakeet Ultra', available: c.parakeetInstalled && !c.previewDisabledByEnv, experimental: true, note: parakeetNote },
+    { id: 'nemotron-560', label: 'Nemotron streaming 560 ms', available: false, experimental: true,
+      note: 'Not wired in this server: FluidAudio 0.17.4 runs Nemotron only as a whole-file batch, so it cannot stream a live preview yet.' },
+  ]
+}
+
+export function hqOptions(c: SttCapabilities): SttOption[] {
+  const lv3 = c.hqLargeV3 ? '' : 'Needs whisper-cli and the Large-v3 weights. '
+  return [
+    { id: 'large-v3', label: 'Whisper Large-v3', available: c.hqLargeV3, experimental: false, note: `${lv3}Word timestamps on, mapped through Whisper's own speech segments.`.trim() },
+    { id: 'large-v3-legacy', label: 'Whisper Large-v3 (legacy decoder)', available: c.hqLargeV3, experimental: false, note: `${lv3}The pre-6.72 decoder without timestamps. Kept for rollback.`.trim() },
+    { id: 'parakeet-ultra', label: 'Parakeet Ultra', available: c.parakeetInstalled, experimental: true,
+      note: c.parakeetInstalled ? 'Lower silver WER than Large-v3, weaker on names; see the evaluation.' : 'Install Parakeet on this Mac first.' },
+  ]
+}
+
+export function secondOpinionOptions(c: SttCapabilities): SttOption[] {
+  return [
+    { id: 'off', label: 'Off', available: true, experimental: false, note: 'One engine only.' },
+    { id: 'parakeet-ultra', label: 'Parakeet Ultra', available: c.parakeetInstalled, experimental: false,
+      note: c.parakeetInstalled ? 'Hears every saved meeting again on the Neural Engine, about 0.6 s per 30 s of audio, after the meeting is saved. Disagreements are saved with the meeting.' : 'Install Parakeet on this Mac first.' },
+    { id: 'large-v3', label: 'Whisper Large-v3', available: c.hqLargeV3, experimental: false, note: 'For a Parakeet HQ model. Adds a full Large-v3 pass to every saved meeting: about 0.2x the audio length on Metal, about 1x on a busy CPU.' },
+  ]
+}
+
+const FRONT_END_OPTIONS: SttOption[] = [
+  { id: 'highpass', label: 'Highpass only', available: true, experimental: false, note: '80 Hz highpass. Does not lift faint background speech over the speech detector.' },
+  { id: 'full', label: 'Full chain', available: true, experimental: false, note: 'Highpass, noise reduction and loudness normalization (before 6.72).' },
+]
+const QUIET_GATE_OPTIONS: SttOption[] = [
+  { id: 'silero', label: 'Speech detector', available: true, experimental: false, note: 'A chunk with under 0.5 s of detected speech is treated as quiet.' },
+  { id: 'rms', label: 'Volume threshold', available: true, experimental: false, note: 'RMS below 150 (before 6.72). Rarely fires on G2 audio.' },
+]
+
+/** The engine family a choice decodes with; a second opinion must differ from HQ. */
+export function engineFamily(id: HqId | SecondOpinionId): 'whisper' | 'parakeet' | 'off' {
+  return id === 'off' ? 'off' : id.startsWith('parakeet') ? 'parakeet' : 'whisper'
+}
+
+export class SttSettingsError extends Error {
+  constructor(message: string) { super(message); this.name = 'SttSettingsError' }
+}
+
+const KEYS = ['preview', 'hq', 'secondOpinion', 'resolver', 'frontEnd', 'quietGate'] as const
+
+/**
+ * Apply a partial PUT. Throws SttSettingsError with a plain sentence for an
+ * unknown key, an unknown id, an unavailable choice or a conflict.
+ * Changing HQ onto the second opinion's engine moves the second opinion to the
+ * other engine (unless the same request sets it), so one tap never fails.
+ */
+export function applySettingsPatch(current: SttSettings, body: unknown, c: SttCapabilities): SttSettings {
+  if (!body || typeof body !== 'object' || Array.isArray(body)) throw new SttSettingsError('Send a JSON object, for example {"hq":"large-v3"}.')
+  const patch = body as Record<string, unknown>
+  const unknown = Object.keys(patch).filter(k => !(KEYS as readonly string[]).includes(k))
+  if (unknown.length) throw new SttSettingsError(`Unknown setting: ${unknown.join(', ')}.`)
+  const next = { ...current }
+  const choose = <T extends string>(key: string, ids: readonly T[], options: SttOption[], label: string): T | undefined => {
+    if (!(key in patch)) return undefined
+    const value = patch[key]
+    if (typeof value !== 'string' || !(ids as readonly string[]).includes(value)) {
+      throw new SttSettingsError(`${label} must be one of: ${ids.join(', ')}.`)
+    }
+    const option = options.find(o => o.id === value)
+    if (option && !option.available) throw new SttSettingsError(`${option.label} is not available: ${option.note}`)
+    return value as T
+  }
+  const preview = choose('preview', PREVIEW_IDS, previewOptions(c), 'Preview model')
+  const hq = choose('hq', HQ_IDS, hqOptions(c), 'HQ model')
+  const second = choose('secondOpinion', SECOND_OPINION_IDS, secondOpinionOptions(c), 'Second opinion')
+  const frontEnd = choose('frontEnd', FRONT_END_IDS, FRONT_END_OPTIONS, 'Front end')
+  const quietGate = choose('quietGate', QUIET_GATE_IDS, QUIET_GATE_OPTIONS, 'Quiet gate')
+  if ('resolver' in patch && typeof patch.resolver !== 'boolean') throw new SttSettingsError('resolver must be true or false.')
+  if (preview) next.preview = preview
+  if (hq) next.hq = hq
+  if (second) next.secondOpinion = second
+  if (frontEnd) next.frontEnd = frontEnd
+  if (quietGate) next.quietGate = quietGate
+  if (typeof patch.resolver === 'boolean') next.resolver = patch.resolver
+  if (engineFamily(next.hq) === engineFamily(next.secondOpinion)) {
+    if (second) throw new SttSettingsError('The second opinion must be a different engine from the HQ model.')
+    const other: SecondOpinionId = engineFamily(next.hq) === 'parakeet' ? 'large-v3' : 'parakeet-ultra'
+    const otherOk = secondOpinionOptions(c).find(o => o.id === other)?.available
+    next.secondOpinion = otherOk ? other : 'off'
+  }
+  return next
+}
+
+// ── Effective choices ─────────────────────────────────────────────────────────
+
+export interface EffectiveStt {
+  settings: SttSettings
+  preview: { engine: 'turbo' | 'large-v3' | 'parakeet'; reason: string | null }
+  hq: { engine: HqId; reason: string | null }
+  secondOpinion: { engine: SecondOpinionId; reason: string | null }
+  resolver: boolean
+  frontEnd: FrontEndId
+  quietGate: QuietGateId
+}
+
+export const REASON_TEXT: Record<string, string> = {
+  parakeet_not_installed: 'Parakeet is not installed on this Mac.',
+  parakeet_warming: 'Parakeet is warming up.',
+  parakeet_warm_failed: 'Parakeet could not start; using Turbo.',
+  parakeet_breaker_open: 'Parakeet missed several previews; using Turbo for a few minutes.',
+  large_v3_preview_not_offered: 'A Large-v3 preview is not offered; using Turbo.',
+  nemotron_not_wired: 'Nemotron preview is not available in this server; using Turbo.',
+  large_v3_unavailable: 'Large-v3 is not available on this Mac.',
+  same_engine_as_hq: 'Same engine as the HQ model.',
+  no_second_opinion: 'No second opinion is running, so nothing to refine with.',
+}
+
+/** What will actually run, given what is installed. A stored choice that is no
+ *  longer possible falls back (preview to Turbo, HQ to Large-v3, second opinion
+ *  to off) and says why with a code. */
+export function effectiveStt(settings: SttSettings, c: SttCapabilities): EffectiveStt {
+  let preview: EffectiveStt['preview'] = { engine: 'turbo', reason: null }
+  if (settings.preview === 'large-v3') preview = { engine: 'turbo', reason: 'large_v3_preview_not_offered' }
+  else if (settings.preview === 'parakeet') {
+    preview = !c.parakeetInstalled ? { engine: 'turbo', reason: 'parakeet_not_installed' }
+      : c.parakeetPreviewBreakerOpen ? { engine: 'turbo', reason: 'parakeet_breaker_open' }
+        : c.parakeetPreviewWarm ? { engine: 'parakeet', reason: null }
+          : c.parakeetPreviewWarmFailed ? { engine: 'turbo', reason: 'parakeet_warm_failed' }
+            : { engine: 'turbo', reason: 'parakeet_warming' }
+  } else if (settings.preview === 'nemotron-560') preview = { engine: 'turbo', reason: 'nemotron_not_wired' }
+  let hq: EffectiveStt['hq'] = { engine: settings.hq, reason: null }
+  if (settings.hq === 'parakeet-ultra' && !c.parakeetInstalled) hq = { engine: 'large-v3', reason: 'parakeet_not_installed' }
+  let second: EffectiveStt['secondOpinion'] = { engine: settings.secondOpinion, reason: null }
+  if (engineFamily(second.engine) === 'parakeet' && !c.parakeetInstalled) second = { engine: 'off', reason: 'parakeet_not_installed' }
+  if (second.engine === 'large-v3' && !c.hqLargeV3) second = { engine: 'off', reason: 'large_v3_unavailable' }
+  if (second.engine !== 'off' && engineFamily(second.engine) === engineFamily(hq.engine)) second = { engine: 'off', reason: 'same_engine_as_hq' }
+  return {
+    settings,
+    preview,
+    hq,
+    secondOpinion: second,
+    resolver: settings.resolver && second.engine !== 'off',
+    frontEnd: settings.frontEnd,
+    quietGate: settings.quietGate,
+  }
+}
+
+export interface ParakeetStatus {
+  installed: boolean
+  installable: boolean
+  version: string
+  bytes: number
+  progress: { state: string; bytesDone: number; bytesTotal: number; error: string | null; source?: unknown }
+  warm: { preview: string; error?: string; at?: string }
+  preview?: { breaker: { open: boolean; retryAt: string | null; misses: number }; counters: Record<string, number> }
+  note: string
+}
+
+function slotReason(code: string | null): { reason: string | null; reasonCode: string | null } {
+  return { reason: code ? (REASON_TEXT[code] ?? code) : null, reasonCode: code }
+}
+
+export function settingsView(settings: SttSettings, c: SttCapabilities, parakeet: ParakeetStatus, lastJob: LastSttJob | null = null) {
+  const eff = effectiveStt(settings, c)
+  const resolverCode = settings.resolver && !eff.resolver ? 'no_second_opinion' : null
+  return {
+    preview: {
+      selected: settings.preview, effective: eff.preview.engine, ...slotReason(eff.preview.reason), options: previewOptions(c),
+      models: [...PREVIEW_MODEL_STRINGS], clientParam: PREVIEW_MODELS_PARAM, requiresApp: PREVIEW_REQUIRES_APP,
+      note: `Only phones that list a preview model in ${PREVIEW_MODELS_PARAM} get it (COS Glasses ${PREVIEW_REQUIRES_APP} and later); every other client gets Whisper Turbo.`,
+    },
+    hq: { selected: settings.hq, effective: eff.hq.engine, ...slotReason(eff.hq.reason), options: hqOptions(c) },
+    secondOpinion: { selected: settings.secondOpinion, effective: eff.secondOpinion.engine, ...slotReason(eff.secondOpinion.reason), options: secondOpinionOptions(c) },
+    resolver: { enabled: settings.resolver, effective: eff.resolver, ...slotReason(resolverCode) },
+    frontEnd: { selected: settings.frontEnd, options: FRONT_END_OPTIONS },
+    quietGate: { selected: settings.quietGate, options: QUIET_GATE_OPTIONS },
+    parakeet,
+    lastJob,
+    appliesTo: { preview: 'next live chunk', hq: 'next saved meeting' },
+  }
+}

package/server/lib/vad-silero.ts

@@ -27,6 +27,12 @@ const MIN_SAMPLES = 512
 let sherpaOnnx: any = null
 let available = false
 let vadInstance: any = null
+// 6.72.0 quiet gate: its own detector, stricter than the trimming one. Chosen on
+// bake-off canary 5 (docs/stt-672-evaluation.md): probability 0.8 with a 0.25 s
+// minimum, and quiet below 0.5 s of speech, fired on 80.8% of Silero-negative
+// chunks and 0.91% of speech chunks.
+export const QUIET_GATE_VAD = { threshold: 0.8, minSilenceDuration: 0.3, minSpeechDuration: 0.25 } as const
+let gateVad: any = null
 
 export interface TrimResult {
   trimmedWav: Buffer
@@ -60,6 +66,11 @@ export function initSileroVAD(): boolean {
       10,  // bufferSizeInSeconds — chunks are max 6s
     )
     vadInstance.reset()  // verify it works
+    gateVad = new sherpaOnnx.Vad(
+      { sileroVad: { model: MODEL_PATH, ...QUIET_GATE_VAD, windowSize: 512 }, sampleRate: SAMPLE_RATE, numThreads: 1, provider: 'cpu' },
+      10,
+    )
+    gateVad.reset()
     available = true
     console.log('[silero-vad] Initialized: Silero VAD active (reused instance, bufferSize=10s)')
     return true
@@ -182,3 +193,44 @@ export function trimSilence(wavBuffer: Buffer): TrimResult {
     return fallback
   }
 }
+
+/**
+ * Seconds of speech the quiet-gate Silero (QUIET_GATE_VAD) hears in a WAV (6.72.0).
+ *
+ * Feeds the detector one 512-sample window at a time and drains finished
+ * segments after each window. Handing sherpa-onnx the whole chunk in one
+ * acceptWaveform call (as trimSilence does) keeps only the last segment:
+ * measured 2026-10-13, a 6 s chunk of continuous speech read 0.32 s that way
+ * and 5.03 s windowed. Null when the detector is unavailable or the audio is
+ * too short to measure: a caller must never read null as silence.
+ */
+export function measureSpeechSeconds(wavBuffer: Buffer): number | null {
+  if (!available || !gateVad) return null
+  try {
+    if (wavBuffer.length <= WAV_HEADER_SIZE + MIN_SAMPLES * BYTES_PER_SAMPLE) return null
+    const pcmBytes = wavBuffer.buffer.slice(wavBuffer.byteOffset + WAV_HEADER_SIZE, wavBuffer.byteOffset + wavBuffer.length - ((wavBuffer.length - WAV_HEADER_SIZE) % 2))
+    const int16 = new Int16Array(pcmBytes)
+    if (int16.length < MIN_SAMPLES) return null
+    const float32 = new Float32Array(int16.length)
+    for (let i = 0; i < int16.length; i++) float32[i] = int16[i] / 32768
+    gateVad.reset()
+    let speechSamples = 0
+    const drain = () => {
+      while (!gateVad.isEmpty()) {
+        speechSamples += gateVad.front().samples.length
+        gateVad.pop()
+      }
+    }
+    for (let offset = 0; offset + MIN_SAMPLES <= float32.length; offset += MIN_SAMPLES) {
+      gateVad.acceptWaveform(float32.subarray(offset, offset + MIN_SAMPLES))
+      drain()
+    }
+    gateVad.flush()
+    drain()
+    gateVad.reset()
+    return speechSamples / SAMPLE_RATE
+  } catch (err: any) {
+    console.error('[silero-vad] measureSpeechSeconds error:', err.message)
+    return null
+  }
+}

package/server/lib/whisper-batch-timing.ts

@@ -1,11 +1,21 @@
 import type { WhisperWord } from './whisper-local.js'
+import { readSttSettings } from './stt-settings.js'
 
-/** Canary-only until human-corrected meeting/fact and native contention gates pass.
+/** Meeting batch HQ timestamps (6.72.0 default: on). The HQ setting decides:
+ * "large-v3" decodes with timestamps and remaps them through Whisper's own VAD
+ * table; "large-v3-legacy" keeps the pre-6.72 `--no-timestamps` decoder.
+ * COS_BATCH_HQ_TIMESTAMPS still overrides: "1" forces timestamps on, "0" off.
  * Live HTTP keeps compact JSON; interactive HQ and DTW are unchanged. */
-export function batchTimestampCanaryEnabled(): boolean {
-  return process.env.COS_BATCH_HQ_TIMESTAMPS === '1'
+export function batchTimestampsEnabled(hq?: string): boolean {
+  const flag = process.env.COS_BATCH_HQ_TIMESTAMPS
+  if (flag === '1') return true
+  if (flag === '0') return false
+  return (hq ?? readSttSettings().hq) !== 'large-v3-legacy'
 }
 
+/** Pre-6.72 name, kept for callers and tests. */
+export const batchTimestampCanaryEnabled = (): boolean => batchTimestampsEnabled()
+
 export interface VadTimeSegment {
   originalStart: number
   originalEnd: number

package/server/lib/whisper-local.ts

@@ -13,7 +13,8 @@ import { writeFileSync, unlinkSync, existsSync, readFileSync, statSync } from 'n
 import { basename, join } from 'node:path'
 import { homedir } from 'node:os'
 import crypto from 'node:crypto'
-import { batchTimestampCanaryEnabled, remapBatchWords } from './whisper-batch-timing.js'
+import { batchTimestampsEnabled, parseNativeVadTimeline, remapBatchWords } from './whisper-batch-timing.js'
+import { readSttSettings, type FrontEndId } from './stt-settings.js'
 import { getVocabulary, getOwnerName, getWhisperCorrections } from './profile.js'
 import { stripBrandUrls } from './hallucination-filter.js'
 import {
@@ -70,21 +71,34 @@ export interface HighQualityTranscriptionCapability {
 export interface HighQualityTranscriptionResult {
   text: string
   words?: WhisperWord[]
+  /** Sub-word tokens merged into spoken words (6.72.0), NOT name-corrected.
+   *  Clocks are only meaningful when the decode ran with timestamps. */
+  spokenWords?: WhisperWord[]
+  /** True when this decode ran with timestamps and the VAD remap. */
+  timestamps?: boolean
+  /** Where this decode's own VAD heard speech (seconds, input clock). Timestamp mode only. */
+  speechSpans?: Array<[number, number]>
   model: 'large-v3' | 'turbo'
   backend: 'whisper-cli' | 'whisper-server'
   actualQuality: 'hq' | 'fast'
   degradationReason?: HighQualityUnavailableReason
 }
 
-let highQualityCheckpointFingerprint: string | null = null
-let highQualityCheckpointTimingMode: boolean | null = null
+const highQualityCheckpointFingerprints = new Map<string, string>()
 
 /** Stable, path-free cache identity for progressive meeting HQ checkpoints.
  * Model/configuration is immutable for the lifetime of one server process, so
- * cache this instead of stat'ing multi-GB model files on every health poll. */
-export function getHighQualityCheckpointFingerprint(): string {
-  const timingMode = batchTimestampCanaryEnabled()
-  if (highQualityCheckpointFingerprint && highQualityCheckpointTimingMode === timingMode) return highQualityCheckpointFingerprint
+ * cache this instead of stat'ing multi-GB model files on every health poll.
+ * 6.72.0: the timing mode and the ASR front end are part of the identity, so a
+ * checkpoint decoded under one setting is never reused under another. With
+ * timestamps off and the full front end the identity is the pre-6.72 one, byte
+ * for byte. */
+export function getHighQualityCheckpointFingerprint(opts: { timestamps?: boolean; frontEnd?: FrontEndId } = {}): string {
+  const timingMode = opts.timestamps ?? batchTimestampsEnabled()
+  const frontEnd: FrontEndId = opts.frontEnd ?? readSttSettings().frontEnd
+  const cacheKey = `${timingMode ? 1 : 0}|${frontEnd}`
+  const cached = highQualityCheckpointFingerprints.get(cacheKey)
+  if (cached) return cached
   const identity = (path: string): Record<string, number | boolean> => {
     try {
       const stat = statSync(path)
@@ -93,9 +107,9 @@ export function getHighQualityCheckpointFingerprint(): string {
       return { present: false, size: 0, mtimeMs: 0 }
     }
   }
-  highQualityCheckpointFingerprint = crypto.createHash('sha256').update(JSON.stringify({
+  const fingerprint = crypto.createHash('sha256').update(JSON.stringify({
     schema: 2,
-    // Keep the existing legacy identity byte-for-byte when the canary is off.
+    // Keep the existing legacy identity byte-for-byte when timestamps are off.
     ...(timingMode ? { batchTiming: 'native-vad-timestamps-v1' } : {}),
     serverVersion: process.env.COS_SERVER_VERSION?.trim() || 'development',
     whisperCli: identity(WHISPER_CLI),
@@ -104,12 +118,12 @@ export function getHighQualityCheckpointFingerprint(): string {
     beam: 5,
     bestOf: 5,
     vadEnabled: hqCliVadEnabled('batch'),
-    enhancement: 'audio-enhance-v1',
+    enhancement: frontEnd === 'full' ? 'audio-enhance-v1' : 'audio-enhance-highpass-v1',
     prompt: buildWhisperPrompt(),
     corrections: getWhisperCorrections(),
   })).digest('hex')
-  highQualityCheckpointTimingMode = timingMode
-  return highQualityCheckpointFingerprint
+  highQualityCheckpointFingerprints.set(cacheKey, fingerprint)
+  return fingerprint
 }
 
 export function classifyHighQualityTranscriptionCapability(input: {
@@ -882,7 +896,7 @@ async function reconcileWhisperServerHealth(): Promise<boolean> {
  * Batch/save path only. Never uses whisper-server `verbose_json` (the live
  * VAD-empty crash vector). Special tokens like `[_BEG_]` / `<|...|>` are dropped.
  */
-export function parseWhisperCliFullJson(raw: string): { text: string; words: WhisperWord[] } {
+export function parseWhisperCliFullJson(raw: string): { text: string; words: WhisperWord[]; spokenWords: WhisperWord[] } {
   const data = JSON.parse(raw) as {
     transcription?: Array<{
       text?: unknown
@@ -896,6 +910,7 @@ export function parseWhisperCliFullJson(raw: string): { text: string; words: Whi
   const segments = Array.isArray(data.transcription) ? data.transcription : []
   const texts: string[] = []
   const words: WhisperWord[] = []
+  const spokenWords: WhisperWord[] = []
 
   for (const segment of segments) {
     if (typeof segment.text === 'string' && segment.text.trim()) {
@@ -909,18 +924,30 @@ export function parseWhisperCliFullJson(raw: string): { text: string; words: Whi
       const fromMs = typeof token.offsets?.from === 'number' ? token.offsets.from : Number(token.offsets?.from)
       const toMs = typeof token.offsets?.to === 'number' ? token.offsets.to : Number(token.offsets?.to)
       if (!Number.isFinite(fromMs) || !Number.isFinite(toMs)) continue
-      words.push({
+      const word: WhisperWord = {
         word: tokenText,
         start: fromMs / 1000,
         end: toMs / 1000,
         probability: typeof token.p === 'number' && Number.isFinite(token.p) ? token.p : 0,
-      })
+      }
+      words.push(word)
+      // A token without a leading space continues the previous word ("I" + "'m").
+      const rawText = typeof token.text === 'string' ? token.text : ''
+      const last = spokenWords.at(-1)
+      if (last && !/^\s/.test(rawText) && !/^[\s]*$/.test(rawText)) {
+        last.word += tokenText
+        last.end = Math.max(last.end, word.end)
+        last.probability = Math.min(last.probability, word.probability)
+      } else {
+        spokenWords.push({ ...word })
+      }
     }
   }
 
   return {
     text: texts.join(' ').replace(/\s+/g, ' ').trim(),
     words,
+    spokenWords,
   }
 }
 
@@ -949,6 +976,8 @@ export async function transcribeHighQuality(
     threads?: number
     backgroundCpu?: boolean
     signal?: AbortSignal
+    /** Meeting batch only: timestamps on/off for this decode (the job's snapshot). */
+    timestamps?: boolean
   } = {},
 ): Promise<HighQualityTranscriptionResult> {
   if (!cliAvailable) {
@@ -972,7 +1001,9 @@ export async function transcribeHighQuality(
   // Word clocks on post-meeting CPU polish, and on any decode that asks for
   // them (the prompt tail guard). Other live decodes stay compact JSON.
   const captureWords = opts.priority === 'batch' || opts.words === true
-  const timestampCanary = opts.priority === 'batch' && batchTimestampCanaryEnabled()
+  // 6.72.0: on by default for meeting batch (HQ setting "large-v3"); the job
+  // passes its own snapshot so a settings change never lands mid-meeting.
+  const timestampCanary = opts.priority === 'batch' && (opts.timestamps ?? batchTimestampsEnabled())
   let nativeDiagnostics = ''
 
   const modelPath = resolveBatchModel()
@@ -1144,6 +1175,8 @@ export async function transcribeHighQuality(
 
     let finalText = text
     let words: WhisperWord[] | undefined
+    let spokenWords: WhisperWord[] | undefined
+    let speechSpans: Array<[number, number]> | undefined
     if (captureWords) {
       try {
         if (existsSync(jsonPath)) {
@@ -1157,6 +1190,11 @@ export async function transcribeHighQuality(
           words = timed.length > 0
             ? timed.map(w => ({ ...w, word: applyCorrections(w.word) }))
             : []
+          // Spoken words stay uncorrected: the resolver joins them and corrects the text once.
+          spokenWords = timestampCanary ? remapBatchWords(parsed.spokenWords, nativeDiagnostics, useVad) : parsed.spokenWords
+          if (timestampCanary && useVad && parsed.words.length) {
+            speechSpans = parseNativeVadTimeline(nativeDiagnostics).map(s => [s.originalStart, s.originalEnd] as [number, number])
+          }
         } else if (timestampCanary) {
           throw new Error('HQ timestamp candidate did not produce CLI JSON')
         }
@@ -1193,7 +1231,10 @@ export async function transcribeHighQuality(
             ? 'large_v3_model_missing' as const
             : 'hq_disabled' as const,
         }
-    return words ? { text: corrected, words, ...metadata } : { text: corrected, ...metadata }
+    const timing = isBatch ? { timestamps: timestampCanary } : {}
+    return words
+      ? { text: corrected, words, ...(spokenWords ? { spokenWords } : {}), ...(speechSpans ? { speechSpans } : {}), ...timing, ...metadata }
+      : { text: corrected, ...timing, ...metadata }
   } finally {
     try { unlinkSync(tmpWav) } catch { /* cleanup */ }
     if (captureWords) {

package/server/routes/meeting.ts

@@ -66,6 +66,7 @@ import {
 import {
   canDeletePendingBatchAudio,
   persistBatchDecisionSidecar,
+  persistSttSidecar,
   replaceMeetingTranscriptAtomic,
 } from '../lib/meeting-batch-persistence.js'
 import {
@@ -77,6 +78,8 @@ import {
 import {
   enqueueSerializedHqWork,
   runMeetingBatchPipeline,
+  recoveryHqJob,
+  summarizeStt,
   segmentTranscriptChunks,
   stopProgressiveHqSession,
   transcribeSegments,
@@ -2178,9 +2181,9 @@ export function createMeetingRouter(deps: MeetingRouteDependencies = {}): Router
       // decoder serialization — that lives in the queue tail. Chain onto it,
       // or two back-to-back recoveries plus a live post-meeting batch would
       // run parallel 16-thread large-v3 decoders on the user's Mac.
-      const results = await enqueueSerializedHqWork(
-        () => transcribeSegments(quarantineDir, segments, entries),
-      )
+      const hqJob = recoveryHqJob(quarantineDir, segments, entries)
+      const plan = hqJob.plan
+      const results = await enqueueSerializedHqWork(hqJob.run)
       // Batch whisper over a dead session has no streaming baseline to
       // compare against (evaluateBatchQuality needs one), but the inline
       // hallucination filter needs none — run the same two-pass the boot
@@ -2240,6 +2243,9 @@ export function createMeetingRouter(deps: MeetingRouteDependencies = {}): Router
         })),
         transferIntegrity: null,
       })
+      try { persistSttSidecar(saved.sidecarPath, results, summarizeStt(plan, results, segments.length)) } catch (error) {
+        console.warn(`[meeting/orphans] ${sessionId}: STT hypotheses not saved: ${error instanceof Error ? error.message : error}`)
+      }
       markRecovered(quarantineDir, saved.filename)
       console.log(
         `[meeting/orphans] Recovered ${sessionId} → ${saved.filename} `