@gotcos/glasses-server 6.15.3 → 6.15.5

package/server/lib/maintenance-lifecycle.ts

@@ -310,6 +310,7 @@ export class MaintenanceLifecycle {
   private blockedGateReason: BlockedGateReason | null = null
   private blockedGateVersion: number | null = null
   private readonly work = new Map<string, WorkEntry>()
+  private readonly admissionsOpenListeners = new Set<() => void>()
 
   constructor(options: MaintenanceLifecycleOptions = {}) {
     this.path = options.path ?? process.env.COS_MAINTENANCE_GATE_PATH?.trim() ?? DEFAULT_GATE_PATH
@@ -356,11 +357,44 @@ export class MaintenanceLifecycle {
     try {
       removeGate(this.path)
       this.gate = null
+      this.notifyAdmissionsOpen()
     } catch {
       this.blockedGateReason = 'invalid_schema'
     }
   }
 
+  /**
+   * Register deferred runtime initialization that is safe only after the
+   * durable maintenance gate opens. Delivery is asynchronous so the release
+   * response is never held open by model/cache initialization. The callback is
+   * also delivered for an already-open lifecycle, closing the boot/release
+   * race without forcing index.ts to poll.
+   */
+  onAdmissionsOpen(listener: () => void): () => void {
+    this.expireSameBootGateIfPermitted()
+    this.admissionsOpenListeners.add(listener)
+    if (!this.gate && !this.blockedGateReason) this.deliverAdmissionsOpen(listener)
+    return () => { this.admissionsOpenListeners.delete(listener) }
+  }
+
+  private deliverAdmissionsOpen(listener: () => void): void {
+    queueMicrotask(() => {
+      if (!this.admissionsOpenListeners.has(listener)) return
+      // State may have closed again between scheduling and microtask delivery.
+      // Never start admitted runtime from a stale accepting notification.
+      this.expireSameBootGateIfPermitted()
+      if (this.gate || this.blockedGateReason) return
+      try { listener() } catch (error) {
+        console.error('[maintenance] admissions-open listener failed:', error)
+      }
+    })
+  }
+
+  private notifyAdmissionsOpen(): void {
+    if (this.gate || this.blockedGateReason) return
+    for (const listener of this.admissionsOpenListeners) this.deliverAdmissionsOpen(listener)
+  }
+
   private credentialsMatch(credentials: MaintenanceOperationCredentials): {
     leaseMatches: boolean
     operationMatches: boolean
@@ -615,6 +649,7 @@ export class MaintenanceLifecycle {
       )
     }
     this.gate = null
+    this.notifyAdmissionsOpen()
   }
 
   cancelDrain(identity: MaintenanceOperationIdentity, credentials: MaintenanceOperationCredentials): void {
@@ -641,6 +676,7 @@ export class MaintenanceLifecycle {
       )
     }
     this.gate = null
+    this.notifyAdmissionsOpen()
   }
 
   snapshot(credentials: MaintenanceOperationCredentials = {}, extraActiveByKind: Record<string, number> = {}) {
@@ -741,6 +777,10 @@ export function maintenanceAdmissionsOpen(): boolean {
   return maintenanceLifecycle.snapshot().admissionsOpen
 }
 
+export function onMaintenanceAdmissionsOpen(listener: () => void): () => void {
+  return maintenanceLifecycle.onAdmissionsOpen(listener)
+}
+
 export function maintenanceErrorPayload(error: MaintenanceLifecycleError) {
   return {
     error: error.code,

package/server/lib/provider-process-lifecycle.ts

@@ -0,0 +1,139 @@
+import type { ChildProcess } from 'node:child_process'
+
+export interface ProviderTerminationResult {
+  closed: boolean
+  escalated: boolean
+  code: number | null
+  signal: NodeJS.Signals | null
+}
+
+interface ProviderTerminationOptions {
+  termGraceMs?: number
+  killWaitMs?: number
+}
+
+/** A detached provider's process group can outlive its CLI leader. ESRCH is
+ * the only proof that no member remains; EPERM and unknown probe failures are
+ * treated as alive so lifecycle ownership fails closed. */
+function providerGroupAlive(pid: number | undefined): boolean {
+  if (!pid || process.platform === 'win32') return false
+  try {
+    process.kill(-pid, 0)
+    return true
+  } catch (error: any) {
+    return error?.code !== 'ESRCH'
+  }
+}
+
+/** Signal the detached provider process group so tool subprocesses cannot be
+ * orphaned behind the CLI wrapper. Direct-child signaling is a safe fallback
+ * for a process that failed before its process group was established. */
+function signalProviderTree(proc: ChildProcess, signal: NodeJS.Signals): void {
+  const pid = proc.pid
+  if (pid && process.platform !== 'win32') {
+    try {
+      process.kill(-pid, signal)
+      return
+    } catch {
+      // Fall through to the direct child. close/error remains authoritative.
+    }
+  }
+  try { proc.kill(signal) } catch { /* process already terminal */ }
+}
+
+/**
+ * Terminate provider work and resolve only after Node observes leader close
+ * and the detached process group no longer exists.
+ * A caller must retain its maintenance lease when `closed` is false: releasing
+ * without a close event could let Control restart while a tool is still alive.
+ */
+export function terminateProviderProcess(
+  proc: ChildProcess,
+  options: ProviderTerminationOptions = {},
+): Promise<ProviderTerminationResult> {
+  const termGraceMs = Math.max(10, options.termGraceMs ?? 2_000)
+  const killWaitMs = Math.max(10, options.killWaitMs ?? 2_000)
+  const groupPid = proc.pid
+  const initiallyClosed = proc.exitCode !== null || proc.signalCode !== null
+
+  if (initiallyClosed && !providerGroupAlive(groupPid)) {
+    return Promise.resolve({
+      closed: true,
+      escalated: false,
+      code: proc.exitCode,
+      signal: proc.signalCode,
+    })
+  }
+
+  return new Promise(resolve => {
+    let settled = false
+    let escalated = false
+    let leaderClosed = initiallyClosed
+    let leaderCode = proc.exitCode
+    let leaderSignal = proc.signalCode
+    let escalationTimer: ReturnType<typeof setTimeout> | undefined
+    let terminalTimer: ReturnType<typeof setTimeout> | undefined
+
+    const finish = (result: ProviderTerminationResult) => {
+      if (settled) return
+      settled = true
+      if (escalationTimer) clearTimeout(escalationTimer)
+      if (terminalTimer) clearTimeout(terminalTimer)
+      proc.removeListener('close', onClose)
+      proc.removeListener('error', onError)
+      resolve(result)
+    }
+    const finishIfTreeClosed = (): boolean => {
+      if (!leaderClosed || providerGroupAlive(groupPid)) return false
+      finish({
+        closed: true,
+        escalated,
+        code: leaderCode,
+        signal: leaderSignal,
+      })
+      return true
+    }
+    const onClose = (code: number | null, signal: NodeJS.Signals | null) => {
+      leaderClosed = true
+      leaderCode = code
+      leaderSignal = signal
+      finishIfTreeClosed()
+    }
+    const onError = () => {
+      // A spawn failure has no live process to retain. Running children still
+      // produce close after an error, so wait for that authoritative event.
+      if (!proc.pid) {
+        leaderClosed = true
+        leaderCode = null
+        leaderSignal = null
+        finishIfTreeClosed()
+      }
+    }
+
+    proc.once('close', onClose)
+    proc.once('error', onError)
+    try { proc.stdin?.destroy() } catch { /* best effort */ }
+    signalProviderTree(proc, 'SIGTERM')
+
+    escalationTimer = setTimeout(() => {
+      if (finishIfTreeClosed()) return
+      escalated = true
+      signalProviderTree(proc, 'SIGKILL')
+      const deadline = Date.now() + killWaitMs
+      const pollForTreeExit = () => {
+        if (finishIfTreeClosed()) return
+        if (Date.now() < deadline) {
+          terminalTimer = setTimeout(pollForTreeExit, 25)
+          return
+        }
+        finish({
+          closed: false,
+          escalated: true,
+          code: leaderCode,
+          signal: leaderSignal,
+        })
+      }
+      terminalTimer = setTimeout(pollForTreeExit, 25)
+    }, termGraceMs)
+  })
+}

package/server/lib/provider-proof.ts

@@ -1,5 +1,6 @@
 import { spawn } from 'node:child_process'
 import { cosBrainDir } from './launch-dir.js'
+import { terminateProviderProcess } from './provider-process-lifecycle.js'
 
 export type ProofProvider = 'claude' | 'codex'
 
@@ -21,6 +22,7 @@ interface ProcessResult {
   stdout: string
   stderr: string
   timedOut: boolean
+  aborted: boolean
 }
 
 function runBounded(
@@ -28,15 +30,20 @@ function runBounded(
   args: string[],
   input: string,
   timeoutMs = 120_000,
+  signal?: AbortSignal,
 ): Promise<ProcessResult> {
   return new Promise((resolvePromise) => {
+    if (signal?.aborted) {
+      resolvePromise({ code: null, stdout: '', stderr: '', timedOut: false, aborted: true })
+      return
+    }
     const env = { ...process.env }
     delete env.CLAUDECODE
     const child = spawn(command, args, {
       cwd: cosBrainDir() ?? process.cwd(),
       env,
       stdio: ['pipe', 'pipe', 'pipe'],
-      detached: false,
+      detached: true,
     })
     let stdout = ''
     let stderr = ''
@@ -48,15 +55,25 @@ function runBounded(
       if (settled) return
       settled = true
       clearTimeout(timer)
+      signal?.removeEventListener('abort', abort)
       resolvePromise(result)
     }
     const timer = setTimeout(() => {
-      try { child.kill('SIGKILL') } catch { /* already exited */ }
-      finish({ code: null, stdout, stderr, timedOut: true })
+      void terminateProviderProcess(child, { termGraceMs: 50 }).then(result => {
+        if (result.closed) finish({ code: result.code, stdout, stderr, timedOut: true, aborted: false })
+        else console.error('[provider-proof] timed-out provider did not close after SIGKILL; retaining request ownership')
+      })
     }, timeoutMs)
     timer.unref?.()
-    child.once('error', err => finish({ code: null, stdout, stderr: err.message, timedOut: false }))
-    child.once('close', code => finish({ code, stdout, stderr, timedOut: false }))
+    const abort = () => {
+      void terminateProviderProcess(child).then(result => {
+        if (result.closed) finish({ code: result.code, stdout, stderr, timedOut: false, aborted: true })
+        else console.error('[provider-proof] canceled provider did not close after SIGKILL; retaining request ownership')
+      })
+    }
+    child.once('error', err => finish({ code: null, stdout, stderr: err.message, timedOut: false, aborted: false }))
+    child.once('close', code => finish({ code, stdout, stderr, timedOut: false, aborted: false }))
+    signal?.addEventListener('abort', abort, { once: true })
     child.stdin.on('error', () => { /* close/error is authoritative */ })
     child.stdin.end(input)
   })
@@ -94,12 +111,13 @@ export function codexProofText(stdout: string): string {
 }
 
 function safeProofError(result: ProcessResult): string {
+  if (result.aborted) return 'provider proof canceled'
   if (result.timedOut) return 'provider proof timed out'
   if (result.code !== 0) return `provider process exited ${result.code ?? 'before launch'}`
   return 'provider returned no valid proof response'
 }
 
-async function executeProof(provider: ProofProvider): Promise<ProviderProofResult> {
+async function executeProof(provider: ProofProvider, signal?: AbortSignal): Promise<ProviderProofResult> {
   const started = Date.now()
   const result = provider === 'claude'
     ? await runBounded('claude', [
@@ -110,7 +128,7 @@ async function executeProof(provider: ProofProvider): Promise<ProviderProofResul
       '--allowedTools', '',
       '--system-prompt', PROOF_PROMPT,
       PROOF_PROMPT,
-    ], '')
+    ], '', 120_000, signal)
     : await runBounded('codex', [
       'exec',
       '--sandbox', 'read-only',
@@ -119,7 +137,7 @@ async function executeProof(provider: ProofProvider): Promise<ProviderProofResul
       '--cd', cosBrainDir() ?? process.cwd(),
       '--ephemeral',
       '-',
-    ], PROOF_PROMPT)
+    ], PROOF_PROMPT, 120_000, signal)
   const text = provider === 'claude'
     ? claudeProofText(result.stdout)
     : codexProofText(result.stdout)
@@ -134,12 +152,12 @@ async function executeProof(provider: ProofProvider): Promise<ProviderProofResul
 }
 
 /** Actual no-tool model turn, cached only after success for this server boot. */
-export async function runProviderProof(provider: ProofProvider): Promise<ProviderProofResult> {
+export async function runProviderProof(provider: ProofProvider, signal?: AbortSignal): Promise<ProviderProofResult> {
   const cached = successCache.get(provider)
   if (cached) return { ...cached, cached: true }
   const existing = inFlight.get(provider)
   if (existing) return existing
-  const operation = executeProof(provider).then(result => {
+  const operation = executeProof(provider, signal).then(result => {
     if (result.ok) successCache.set(provider, result)
     return result
   }).finally(() => {

package/server/lib/transcribe-audio.ts

@@ -62,6 +62,12 @@ export class NoSpeechDetectedError extends Error {
 // ceiling (anything longer is a dictation, not a query — use meetings instead).
 const HQ_MAX_SECONDS = 60
 
+/** Short interactive clips use light enhance (highpass only). Override via env. */
+function hqEnhanceLightMaxSeconds(): number {
+  const value = Number.parseInt(process.env.COS_HQ_ENHANCE_LIGHT_MAX_SEC || '15', 10)
+  return Number.isFinite(value) && value >= 0 ? value : 15
+}
+
 function unavailableAfterLocalFailure(): TranscriptionUnavailableError | null {
   const fallback = getTranscriptionPolicySnapshot()
   if (fallback.openaiFallbackReady) return null
@@ -158,10 +164,12 @@ export async function transcribeAudioBuffer(
 
   if (effectiveMode === 'hq') {
     try {
-      const enhanced = await enhanceAudio(audioBuffer)
+      const lightMax = hqEnhanceLightMaxSeconds()
+      const enhanceProfile = audioSeconds < lightMax ? 'light' as const : 'full' as const
+      const enhanced = await enhanceAudio(audioBuffer, { profile: enhanceProfile })
       const result = await transcribeHighQuality(enhanced)
       text = result.text
-      backend = 'hq-large-v3'
+      backend = enhanceProfile === 'light' ? 'hq-large-v3-light' : 'hq-large-v3'
       actualQuality = 'hq'
     } catch (hqErr: any) {
       console.warn(`[transcribe] HQ path failed, falling back to fast: ${hqErr.message}`)

package/server/lib/whisper-local.ts

@@ -6,10 +6,10 @@
 //   2. whisper-cli (spawned per request, model loaded from disk) → ~500-700ms
 //   3. OpenAI API (cloud, handled by transcribe.ts) → ~1000-3000ms
 
-import { spawn, execFileSync } from 'node:child_process'
+import { spawn, execFile } from 'node:child_process'
 import type { ChildProcess } from 'node:child_process'
 import { writeFileSync, unlinkSync, existsSync, readFileSync } from 'node:fs'
-import { join } from 'node:path'
+import { basename, join } from 'node:path'
 import { homedir } from 'node:os'
 import crypto from 'node:crypto'
 import { getVocabulary, getOwnerName } from './profile.js'
@@ -137,6 +137,10 @@ function getWhisperPrompt(): string {
 // whisper-server runs on this port (started at server boot or by LaunchAgent)
 const WHISPER_SERVER_PORT = 8178
 const WHISPER_SERVER_URL = `http://127.0.0.1:${WHISPER_SERVER_PORT}`
+const PROCESS_PROBE_TIMEOUT_MS = 2_000
+const PROCESS_PROBE_MAX_BUFFER = 1024 * 1024
+const PS_BIN = '/bin/ps'
+const LSOF_BIN = existsSync('/usr/sbin/lsof') ? '/usr/sbin/lsof' : 'lsof'
 
 // Track which backends are available
 let cliAvailable = false
@@ -153,6 +157,10 @@ let serverStarting = false            // Initial model load is not a circuit fai
 let serverStartPromise: Promise<void> | null = null
 let serverRestartPromise: Promise<WhisperRestartResult> | null = null
 let serverHealthProbe: Promise<boolean> | null = null
+type WhisperStartupState = 'not_started' | 'preflight' | 'loading' | 'ready' | 'unavailable' | 'failed' | 'stopped'
+let serverStartupState: WhisperStartupState = 'not_started'
+let serverLastAttemptAt: string | null = null
+let serverLastError: string | null = null
 
 interface ProcessEntry {
   pid: number
@@ -167,10 +175,34 @@ export interface WhisperRestartResult {
 
 const sleep = (ms: number): Promise<void> => new Promise(resolve => setTimeout(resolve, ms))
 
-function listProcesses(): ProcessEntry[] {
+function boundedError(value: unknown): string {
+  const message = value instanceof Error ? value.message : String(value)
+  return message.replace(/[\r\n\t]+/g, ' ').slice(0, 240)
+}
+
+function runProcessProbe(file: string, args: string[]): Promise<string> {
+  return new Promise((resolve, reject) => {
+    execFile(file, args, {
+      encoding: 'utf8',
+      timeout: PROCESS_PROBE_TIMEOUT_MS,
+      maxBuffer: PROCESS_PROBE_MAX_BUFFER,
+      killSignal: 'SIGKILL',
+    }, (error, stdout) => {
+      if (error) reject(error)
+      else resolve(String(stdout))
+    })
+  })
+}
+
+async function listProcesses(): Promise<ProcessEntry[]> {
   // `command=` includes arguments, which lets us distinguish this COS-owned
   // port/model signature from unrelated whisper-server instances.
-  const output = execFileSync('ps', ['-axww', '-o', 'pid=,ppid=,command='], { encoding: 'utf8' })
+  let output: string
+  try {
+    output = await runProcessProbe(PS_BIN, ['-axww', '-o', 'pid=,ppid=,command='])
+  } catch (error) {
+    throw new Error(`unable to inspect process table: ${boundedError(error)}`)
+  }
   return output.split('\n').flatMap(line => {
     const match = line.match(/^\s*(\d+)\s+(\d+)\s+(.+?)\s*$/)
     if (!match) return []
@@ -178,24 +210,25 @@ function listProcesses(): ProcessEntry[] {
   })
 }
 
-function listeningPids(): number[] {
+async function listeningPids(): Promise<number[]> {
   try {
-    const output = execFileSync(
-      'lsof',
+    const output = await runProcessProbe(
+      LSOF_BIN,
       ['-nP', `-iTCP:${WHISPER_SERVER_PORT}`, '-sTCP:LISTEN', '-t'],
-      { encoding: 'utf8' },
     )
     return output.split(/\s+/).map(Number).filter(pid => Number.isInteger(pid) && pid > 0)
   } catch (err: any) {
     // lsof uses exit 1 for "no matches". Anything else means we could not
     // prove the port state, so startup must fail closed.
-    if (err?.status === 1) return []
-    throw new Error(`unable to inspect whisper-server port ${WHISPER_SERVER_PORT}: ${err?.message ?? err}`)
+    if (err?.code === 1 || err?.status === 1) return []
+    throw new Error(`unable to inspect whisper-server port ${WHISPER_SERVER_PORT}: ${boundedError(err)}`)
   }
 }
 
 function isCosWhisperServerCommand(command: string): boolean {
-  const executable = /(?:^|\s)(?:\S*\/)?whisper-server(?:\s|$)/.test(command)
+  const firstToken = command.trim().match(/^(?:"([^"]+)"|'([^']+)'|(\S+))/)
+  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)
 }
@@ -249,7 +282,7 @@ async function killAndReapWhisperProcesses(): Promise<void> {
   serverAvailable = false
 
   for (let round = 0; round < 3; round++) {
-    const processes = listProcesses()
+    const processes = await listProcesses()
     const ownedPids = [...ownedServerChildren]
       .map(child => child.pid)
       .filter((pid): pid is number => typeof pid === 'number')
@@ -288,7 +321,7 @@ async function killAndReapWhisperProcesses(): Promise<void> {
     await sleep(50)
   }
 
-  const remaining = listProcesses().filter(entry => isCosWhisperServerCommand(entry.command))
+  const remaining = (await listProcesses()).filter(entry => isCosWhisperServerCommand(entry.command))
   if (remaining.length > 0) {
     throw new Error(`stale whisper-server process(es) remain: ${remaining.map(entry => entry.pid).join(', ')}`)
   }
@@ -298,11 +331,11 @@ async function killAndReapWhisperProcesses(): Promise<void> {
 
 async function proveWhisperPortClear(): Promise<void> {
   for (let attempt = 0; attempt < 20; attempt++) {
-    const pids = listeningPids()
+    const pids = await listeningPids()
     if (pids.length === 0) return
     if (attempt < 19) await sleep(250)
   }
-  const pids = listeningPids()
+  const pids = await listeningPids()
   throw new Error(
     `whisper-server port ${WHISPER_SERVER_PORT} remains occupied${pids.length ? ` by PID(s) ${pids.join(', ')}` : ''}`,
   )
@@ -334,10 +367,17 @@ export async function startWhisperServer(): Promise<void> {
   if (serverAvailable && serverProcess) return
 
   serverStarting = true
+  serverStartupState = 'preflight'
+  serverLastAttemptAt = new Date().toISOString()
+  serverLastError = null
   const operation = startWhisperServerAttempt()
   serverStartPromise = operation
   try {
     await operation
+  } catch (error) {
+    serverStartupState = 'failed'
+    serverLastError = boundedError(error)
+    throw error
   } finally {
     if (serverStartPromise === operation) serverStartPromise = null
     serverStarting = false
@@ -346,6 +386,8 @@ export async function startWhisperServer(): Promise<void> {
 
 async function startWhisperServerAttempt(preflightCompleted = false): Promise<void> {
   if (!existsSync(WHISPER_SERVER) || !existsSync(MODEL_PATH)) {
+    serverStartupState = 'unavailable'
+    serverLastError = 'whisper-server or model not found'
     console.log('[whisper-local] whisper-server or model not found — using CLI fallback')
     return
   }
@@ -353,9 +395,12 @@ async function startWhisperServerAttempt(preflightCompleted = false): Promise<vo
   // The API process is the sole Whisper owner. Never adopt an untracked daemon:
   // reap stale trees, then prove the fixed local port is free before spawning.
   if (!preflightCompleted) {
+    console.log('[whisper-local] preflight: inspecting owned processes and port 8178')
+    serverStartupState = 'preflight'
     await killAndReapWhisperProcesses()
     await proveWhisperPortClear()
   }
+  serverStartupState = 'loading'
 
   // 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).
@@ -402,6 +447,8 @@ async function startWhisperServerAttempt(preflightCompleted = false): Promise<vo
     if (serverProcess !== child) return
     serverAvailable = false
     serverProcess = null
+    serverStartupState = 'failed'
+    serverLastError = `whisper-server exited${code == null ? '' : ` with code ${code}`}`
     if (code !== null && code !== 0) {
       console.warn(`[whisper-local] whisper-server exited with code ${code}`)
     }
@@ -422,6 +469,8 @@ async function startWhisperServerAttempt(preflightCompleted = false): Promise<vo
       const res = await fetch(`${WHISPER_SERVER_URL}/health`, { signal: AbortSignal.timeout(1000) })
       if (res.ok) {
         serverAvailable = true
+        serverStartupState = 'ready'
+        serverLastError = null
         const loadTime = ((Date.now() - startTime) / 1000).toFixed(1)
         console.log(`[whisper-local] whisper-server ready on port ${WHISPER_SERVER_PORT} (loaded in ${loadTime}s)`)
         return
@@ -444,6 +493,8 @@ async function startWhisperServerAttempt(preflightCompleted = false): Promise<vo
   console.error(`[whisper-local] ${failure} — reaping child and keeping local backend unavailable`)
   await killAndReapWhisperProcesses()
   await proveWhisperPortClear()
+  serverStartupState = 'failed'
+  serverLastError = failure
   throw new Error(failure)
 }
 
@@ -461,6 +512,7 @@ export function stopWhisperServer(): void {
     try { proc.kill('SIGKILL') } catch { /* already exited */ }
   }
   ownedHqChildren.clear()
+  serverStartupState = 'stopped'
 }
 
 export function isWhisperLocalAvailable(): boolean {
@@ -480,17 +532,25 @@ export function getWhisperBackend(): 'server' | 'cli' | 'none' {
 /** Detailed health status for diagnostics (/api/health) */
 export function getWhisperHealth(): {
   server: boolean
+  serverConfigured: boolean
   cli: boolean
   consecutiveFailures: number
   restarting: boolean
   circuitOpen: boolean
+  startupState: WhisperStartupState
+  lastAttemptAt: string | null
+  lastError: string | null
 } {
   return {
     server: serverAvailable,
+    serverConfigured: existsSync(WHISPER_SERVER) && existsSync(MODEL_PATH),
     cli: cliAvailable,
     consecutiveFailures: serverConsecutiveFailures,
     restarting: serverRestarting || serverStarting,
     circuitOpen: serverConsecutiveFailures >= SERVER_FAILURE_THRESHOLD,
+    startupState: serverStartupState,
+    lastAttemptAt: serverLastAttemptAt,
+    lastError: serverLastError,
   }
 }
 
@@ -604,14 +664,22 @@ export async function transcribeHighQuality(
 
     const text = await new Promise<string>((resolve, reject) => {
       const isolateBatchFromLiveMetal = opts.priority === 'batch'
+      // Interactive HQ: narrower beam (default 2) for latency. Meeting batch keeps 5.
+      // Override: COS_HQ_BEAM_INTERACTIVE=N
+      const interactiveBeamRaw = Number.parseInt(process.env.COS_HQ_BEAM_INTERACTIVE || '2', 10)
+      const interactiveBeam = Number.isFinite(interactiveBeamRaw) && interactiveBeamRaw >= 1
+        ? Math.min(interactiveBeamRaw, 5)
+        : 2
+      const beam = isolateBatchFromLiveMetal ? 5 : interactiveBeam
+      const bestOf = beam
       const args = [
         '-m', modelPath,
         '-f', tmpWav,
         '-t', isolateBatchFromLiveMetal ? '8' : '16',
         '-l', 'en',
         ...(isolateBatchFromLiveMetal ? ['-ng'] : ['-fa']),
-        '-bs', '5',           // Beam search width 5 (default disabled)
-        '-bo', '5',           // Best-of-5 candidates (default 2)
+        '-bs', String(beam),
+        '-bo', String(bestOf),
         '--no-timestamps',
         '-np',
         '--prompt', buildPrompt(context),
@@ -966,6 +1034,9 @@ export async function restartWhisperServer(): Promise<WhisperRestartResult> {
   if (serverRestartPromise) return serverRestartPromise
 
   serverRestarting = true
+  serverStartupState = 'preflight'
+  serverLastAttemptAt = new Date().toISOString()
+  serverLastError = null
   const priorStart = serverStartPromise
   const operation = (async (): Promise<WhisperRestartResult> => {
     try {
@@ -984,6 +1055,8 @@ export async function restartWhisperServer(): Promise<WhisperRestartResult> {
         throw new Error('whisper-server did not become healthy')
       }
       serverConsecutiveFailures = 0
+      serverStartupState = 'ready'
+      serverLastError = null
       console.log('[whisper-local] Server restarted successfully — circuit breaker CLOSED')
       return { status: 'recovered' }
     } catch (err: any) {
@@ -992,6 +1065,8 @@ export async function restartWhisperServer(): Promise<WhisperRestartResult> {
       // breaker cycle, and the next three failed calls may request one new cycle.
       serverConsecutiveFailures = 0
       const message = err?.message ?? String(err)
+      serverStartupState = 'failed'
+      serverLastError = boundedError(message)
       console.error(`[whisper-local] Server restart error: ${message} — will retry after next 3 failures`)
       return { status: 'failed', error: message }
     }

package/server/routes/health.ts

@@ -180,6 +180,23 @@ healthRouter.get('/health', async (_req, res) => {
   // Whisper-server health + cloud budget — exposed so glasses + dashboards can
   // see whether we're at risk of falling to cloud and how much budget remains.
   const whisper_health = getWhisperHealth()
+  const whisperReadiness = !whisper_health.serverConfigured
+    ? 'not_configured'
+    : whisper_health.server
+      ? 'ready'
+      : whisper_health.startupState === 'preflight' || whisper_health.startupState === 'loading'
+        ? 'starting'
+        : 'degraded'
+  const readiness = {
+    // /api/health remains a liveness endpoint and intentionally returns HTTP
+    // 200 while the server can answer. This separate field prevents an HTTP-
+    // green response from hiding a configured local subsystem failure.
+    status: whisperReadiness === 'degraded' ? 'degraded' : 'ready',
+    admissions: maintenance.admissionsOpen ? 'open' : 'maintenance',
+    whisper: whisperReadiness,
+    whisperError: whisper_health.lastError,
+    localTts: tts_local.ready ? 'ready' : 'unavailable',
+  }
   const openai_whisper_budget = getOpenAIWhisperBudgetState()
   const codex_models = getCodexModelCatalogSnapshot()
   res.json({
@@ -190,6 +207,7 @@ healthRouter.get('/health', async (_req, res) => {
     generation_id: getServerGenerationId(),
     features,
     voice,
+    readiness,
     whisper_health,
     openai_whisper_budget,
     tts_local,