@gotcos/glasses-server 6.73.14 → 6.74.0

package/CHANGELOG.md

@@ -1,3 +1,24 @@
+## 6.74.0 - Mac dictation works for every user, and Parakeet installs from COS Control (local candidate)
+
+- Mac dictation has its own engine setting, `dictation`: `auto` (default), `parakeet-ultra` or `whisper`, saved with the other speech settings (`PUT /api/stt-settings {"dictation":"whisper"}`; GET adds `dictation.desktop` with `selected`, `effective`, `reason`, `reasonCode`, `options` and `note`). It no longer follows the Preview model. Every settings file written before 6.74.0 has no key and reads as `auto`, so a Mac that chose Parakeet keeps it.
+- `POST /api/transcribe?requiredEngine=local` (COS Control 0.5.317): under `auto`, Parakeet Ultra when installed, warm and its breaker closed; otherwise the local Whisper live worker decodes that dictation, a Parakeet warm-up starts, and the answer says so (`engine`, `fallbackReason`, `dictationSetting`). Cold, warming, warm-up failed, breaker open, both interactive slots busy, and a failed Parakeet decode all fall back to Whisper. Never the cloud, even with the OpenAI fallback configured. When nothing local can run: 503 `no_local_engine` with `action` (`install_parakeet`, `retry_when_warm` or `open_transcription_settings`), `detail`, and `retryable` true only when a retry can succeed. The explicit `parakeet-ultra` setting stays strict: 503 `parakeet_unavailable` with the action, never Whisper.
+- `requiredEngine=parakeet-ultra` (COS Control 0.5.316 and earlier) keeps the 6.73 contract: Parakeet only, the same 503 bodies and messages. It now follows the dictation setting rather than the Preview model, so it succeeds wherever Parakeet is installed and warm.
+- `GET /api/transcribe/capabilities` keeps `desktopDictationVersion: 1` (COS Control 0.5.316 accepts exactly 1) and adds `desktopDictationVersions: [1, 2]`, `requiredEngines: ['parakeet-ultra', 'local']` and `benchmark: 1`. COS Control sends `local` only when the list holds 2.
+- Parakeet installs from COS Control. FluidAudio publishes no 0.17.4 binary, so COS Control ships its own signed build in `Contents/Helpers`. The server trusts it when `codesign --verify --strict` passes against a requirement anchored at Apple for the COS team, its TeamIdentifier is the COS team, its codesign identifier and embedded CFBundleIdentifier are both `com.gotcos.control.fluidaudiocli`, and that signed, embedded Info.plist says version 0.17.4 (the upstream 0.17.4 CLI has no version command, and the check never runs the binary). The SHA-256 pinned hand copy still works and wins when present. The installed copy is checked again after it is copied; its hash and size go in the receipt and every run checks them.
+- `POST /api/stt-settings/parakeet/cli {cliPath}` lets COS Control register its CLI and get the verdict (200 trusted, 422 with `reason`: unsigned, signature_invalid, wrong_team, wrong_identifier, wrong_version, missing). The server also looks in `/Applications` and `~/Applications`. `installable` and `note` now reflect it; the note never points at `~/.cos-glasses/bin`.
+- Install: `{cliPath, allowDownload: true}`. A 1.5 GB free-space check runs before anything is written (507 `insufficient_disk` with `freeBytes` and `requiredBytes`). The progress block adds `errorCode` (cancelled, insufficient_disk, sha_mismatch, download_failed, stalled, cli_untrusted, cli_missing). `allowDownload: false` without a local source never downloads. A failed or cancelled install keeps the previous install and Whisper dictation.
+- `POST /api/transcribe/benchmark?engines=whisper,parakeet-ultra` for onboarding: the same 16 kHz WAV through each installed local engine, with `elapsedMs`, `rtf`, `peakRssBytes` (Parakeet only; the Whisper worker is shared and always resident), `warmupMs` for a cold Parakeet, and the text. One run at a time, refused while a recording is live (409), 60 s per engine, 150 s in all.
+- Not changed: phone and glasses dictation still follow the Preview and HQ models. Speaker separation still looks for the CLI only at `COS_NEMOTRON_CLI`, `~/.cos-glasses/bin` and `PATH`, so a GUI Parakeet install does not enable it.
+- Pair with COS Control 0.5.317. Includes 6.73.15. Transcription-candidate and cue flags stay disabled. No public publication is implied.
+
+## 6.73.15 — Work chat knows which sessions still have earlier work open, and takes reference sessions (local candidate)
+
+- Work chat input accepts an optional per-session `openWork` (boolean only; anything else is refused): true when that session still has an earlier handoff from this task open (running, queued, unconfirmed, or a delivered reply not yet checked). It reaches the planner as evidence, and the planner is told such an assignment waits until that work resolves and is never delivered mid-turn, to prefer a free automatic session for independent new work, and to say in the answer when an assignment will wait.
+- GET `/api/work/chat` advertises `queueRounds: true`. Control 0.5.317 queues a held send or sends it in parallel only when it sees this; on an older server it keeps the check-first fence and says so.
+- Reference sessions (Miles 2026-10-16 12:16): Work chat input accepts optional `references` (at most 6; `{id, title, summary, result}`, title 300, summary 2000, result 4000 characters, redacted with the rest). A reference is a session linked to the task as a read-only reference point, usually working on another task: evidence for the planner, cited by title, never an assignment target (an id there may not also be one of `sessions`, and an assignment to it is refused as before) and never counted as this task's progress. GET advertises `references: true` and `maxReferences: 6`. The links themselves are Control's (its session-references file beside the working links); the server stores no session-to-task links.
+- The queue itself is Control's (the round's saved history beside the work journal), dispatched through Control's existing send path, which still parks a turn behind a busy native thread with `session-chat-queue`. Nothing on the server dispatches a queued round, so queued work waits while COS Control is closed.
+- Pair with Control 0.5.317. Older Control sends no `openWork` and is unchanged. Transcription-candidate and cue flags stay disabled. No public publication is implied.
+
 ## 6.73.14 — Saved Mac recordings appear in Meetings; Work chat keeps a plan with a stray item (local candidate)
 
 - A saved Mac recording now lists in Meetings on a Mac whose COS pipeline files G2 recordings (Miles 2026-10-15: the 10:39 PM recording saved but Control said "Saved meeting not found yet" forever). Mac captures never reach the pipeline (routes/meeting.ts, MAC_CAPTURE_ID), and that layout listed only the operations tree. The store's Mac rows now join it (`withMacStoreRows`, standalone identity, an operations copy wins by session), are filtered before the store's 200-row cap, count in the calendar's day dots (`macStoreDayCounts`), and a month holding only Mac recordings reaches the pager. G2 store rows stay the pipeline's.

package/package.json

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

package/server/lib/diarizer-backend.ts

@@ -18,6 +18,8 @@ import { execFileSync } from 'node:child_process'
 import { chmodSync, existsSync, lstatSync, mkdirSync, readlinkSync, statSync, symlinkSync, unlinkSync } from 'node:fs'
 import { homedir } from 'node:os'
 import { join } from 'node:path'
+import { installedCliTrustedNow, parakeetCliPath, pinnedCliKnown } from './parakeet.js'
+import { controlCliCandidates, knownCliTrust } from './parakeet-cli-trust.js'
 
 export type DiarizerMode = 'nemotron' | 'embedding'
 
@@ -57,7 +59,7 @@ export function nemotronCliPath(env: NodeJS.ProcessEnv = process.env, home: stri
   const key = env.PATH ?? ''
   const now = Date.now()
   if (whichCache && whichCache.key === key && now - whichCache.at < WHICH_CACHE_MS) {
-    return whichCache.value && existsSync(whichCache.value) ? whichCache.value : null
+    return whichCache.value && existsSync(whichCache.value) ? whichCache.value : trustedParakeetCli(home)
   }
   let value: string | null = null
   try {
@@ -67,7 +69,27 @@ export function nemotronCliPath(env: NodeJS.ProcessEnv = process.env, home: stri
     value = null
   }
   whichCache = { key, at: now, value }
-  return value
+  return value ?? trustedParakeetCli(home)
+}
+
+/**
+ * 6.74.0, after every earlier location: the Parakeet CLI a GUI install put under
+ * <data>/stt/parakeet/current/bin, then COS Control's bundled copy (Contents/Helpers).
+ * Each only when trusted (a verified install receipt, or a Developer ID build of the COS
+ * team, or the SHA-256 pinned bytes). Never runs anything; an unchecked file is skipped
+ * until its background check lands, so a health read never blocks.
+ */
+export function trustedParakeetCli(home: string = homedir()): string | null {
+  try {
+    if (installedCliTrustedNow() === true) return parakeetCliPath()
+  } catch { /* not installed */ }
+  for (const path of controlCliCandidates(home)) {
+    try {
+      if (!existsSync(path)) continue
+      if (knownCliTrust(path)?.trusted || pinnedCliKnown([path]) === true) return path
+    } catch { /* next */ }
+  }
+  return null
 }
 
 const WHICH_CACHE_MS = 60_000

package/server/lib/dictation-benchmark.ts

@@ -0,0 +1,197 @@
+// 6.74.0: the on-device dictation check COS Control's onboarding runs on its pinned
+// 30 s sample. Each installed local engine decodes the same WAV once; the result is
+// speed (real-time factor), peak memory where it can be measured, and the text.
+// Control scores accuracy against its own reference transcript.
+//
+// One clip is a sanity check on this Mac, not a benchmark of the engine. Bounded:
+// one run at a time, never while a recording is live, a timeout per engine and in all.
+// No cloud and no LLM: Whisper is the local live worker, Parakeet the sandboxed CLI.
+
+import { execFile } from 'node:child_process'
+import { applyCorrections, getWhisperCommitCapability, transcribeLocal } from './whisper-local.js'
+import { parakeetInstalled, parakeetWarmState, transcribeParakeet, warmParakeet, FIRST_LOAD_TIMEOUT_MS } from './parakeet.js'
+import { isRecordingLive, PREVIEW_PARAKEET_MODEL } from './stt-runtime.js'
+import { parakeetDictationTimeoutMs, isPcm16kMonoWav } from './dictation-stt.js'
+
+export const BENCHMARK_ENGINES = ['whisper', 'parakeet-ultra'] as const
+export type BenchmarkEngine = typeof BENCHMARK_ENGINES[number]
+/** One engine (including a Parakeet cold start) gets this long. */
+export const BENCHMARK_ENGINE_TIMEOUT_MS = 60_000
+/** The whole run gets this long. */
+export const BENCHMARK_TOTAL_TIMEOUT_MS = 150_000
+export const BENCHMARK_MAX_BYTES = 3_840_044
+
+export interface BenchmarkEngineResult {
+  engine: BenchmarkEngine
+  /** whisper: the live worker model (large-v3-turbo or large-v3); parakeet-ultra: the pinned model. */
+  model: string
+  ran: boolean
+  skipped?: 'not_installed' | 'unavailable' | 'busy' | 'timeout' | 'total_timeout'
+  error?: string
+  /** Wall time of the decode (warm for Parakeet). */
+  elapsedMs?: number
+  /** elapsed seconds / audio seconds; below 1 is faster than real time. */
+  rtf?: number
+  /** Peak resident memory of the decoding process, when this server can sample it. */
+  peakRssBytes: number | null
+  /** Parakeet only: time to compile and warm the model first, when it was cold. */
+  warmupMs?: number
+  /** The engine's text after the COS dictionary corrections, before the hallucination filters. */
+  text?: string
+}
+
+export interface BenchmarkResult { audioSeconds: number; results: BenchmarkEngineResult[] }
+
+export class BenchmarkRefusedError extends Error {
+  constructor(readonly status: number, readonly reason: 'benchmark_running' | 'recording_live' | 'audio_not_pcm_wav' | 'audio_too_large' | 'invalid_engine', message: string) {
+    super(message)
+    this.name = 'BenchmarkRefusedError'
+  }
+}
+
+export interface BenchmarkDeps {
+  recordingLive: () => boolean
+  whisperPresent: () => boolean
+  whisperModel: () => string
+  whisper: (audio: Buffer, signal: AbortSignal) => Promise<{ text: string }>
+  parakeetInstalled: () => boolean
+  parakeetWarm: () => boolean
+  /** Compile and warm Parakeet; resolves true when warm. */
+  warmParakeet: () => Promise<boolean>
+  parakeet: (audio: Buffer, timeoutMs: number, onSpawn: (pid: number) => void, signal: AbortSignal) => Promise<{ text: string }>
+  /** Resident set size of a pid in bytes, or null. */
+  rss: (pid: number) => Promise<number | null>
+  now: () => number
+  engineTimeoutMs: number
+  totalTimeoutMs: number
+}
+
+function psRss(pid: number): Promise<number | null> {
+  return new Promise(resolve => {
+    execFile('/bin/ps', ['-o', 'rss=', '-p', String(pid)], { timeout: 1_000 }, (error, stdout) => {
+      const kb = Number(String(stdout ?? '').trim())
+      resolve(error || !Number.isFinite(kb) || kb <= 0 ? null : kb * 1024)
+    })
+  })
+}
+
+export const defaultBenchmarkDeps: BenchmarkDeps = {
+  recordingLive: () => isRecordingLive(),
+  whisperPresent: () => getWhisperCommitCapability().configured,
+  whisperModel: () => getWhisperCommitCapability().effectiveModel,
+  // The live worker, as Mac dictation runs it: the vocabulary prompt on, the breaker untouched.
+  whisper: async audio => ({ text: (await transcribeLocal(audio, undefined, undefined, { affectsCircuit: false })).text }),
+  parakeetInstalled: () => parakeetInstalled().installed,
+  parakeetWarm: () => parakeetWarmState(PREVIEW_PARAKEET_MODEL).state === 'warm',
+  warmParakeet: () => warmParakeet(PREVIEW_PARAKEET_MODEL),
+  parakeet: async (audio, timeoutMs, onSpawn, signal) => {
+    const r = await transcribeParakeet(audio, { model: PREVIEW_PARAKEET_MODEL, lane: 'interactive', timeoutMs, onSpawn, signal })
+    return { text: applyCorrections(r.text) }
+  },
+  rss: psRss,
+  now: () => performance.now(),
+  engineTimeoutMs: BENCHMARK_ENGINE_TIMEOUT_MS,
+  totalTimeoutMs: BENCHMARK_TOTAL_TIMEOUT_MS,
+}
+
+let running = false
+export function benchmarkRunning(): boolean { return running }
+export function __resetBenchmarkForTests(): void { running = false }
+
+class Timeout extends Error { constructor(readonly which: 'timeout' | 'total_timeout') { super(which) } }
+
+/** Resolve with the promise, or reject with Timeout after ms. Aborts ctl on timeout. */
+function within<T>(promise: Promise<T>, ms: number, which: 'timeout' | 'total_timeout', ctl: AbortController): Promise<T> {
+  return new Promise<T>((resolve, reject) => {
+    const timer = setTimeout(() => { ctl.abort(); reject(new Timeout(which)) }, Math.max(0, ms))
+    timer.unref?.()
+    promise.then(v => { clearTimeout(timer); resolve(v) }, e => { clearTimeout(timer); reject(e) })
+  })
+}
+
+export function parseBenchmarkEngines(raw: unknown): BenchmarkEngine[] | null {
+  if (raw === undefined || raw === '') return [...BENCHMARK_ENGINES]
+  if (typeof raw !== 'string') return null
+  const list = raw.split(',').map(s => s.trim()).filter(Boolean)
+  if (!list.length || list.some(e => !(BENCHMARK_ENGINES as readonly string[]).includes(e))) return null
+  return [...new Set(list)] as BenchmarkEngine[]
+}
+
+export async function runDictationBenchmark(audio: Buffer, engines: BenchmarkEngine[] = [...BENCHMARK_ENGINES], deps: BenchmarkDeps = defaultBenchmarkDeps): Promise<BenchmarkResult> {
+  if (audio.length > BENCHMARK_MAX_BYTES) throw new BenchmarkRefusedError(413, 'audio_too_large', 'The sample is longer than two minutes.')
+  if (!isPcm16kMonoWav(audio)) throw new BenchmarkRefusedError(400, 'audio_not_pcm_wav', 'The sample must be 16 kHz mono 16-bit WAV.')
+  if (running) throw new BenchmarkRefusedError(409, 'benchmark_running', 'A dictation check is already running.')
+  if (deps.recordingLive()) throw new BenchmarkRefusedError(409, 'recording_live', 'A recording is live. Run the check after it is saved.')
+  running = true
+  try {
+    const audioSeconds = Math.max(0, (audio.length - 44) / 32_000)
+    const started = deps.now()
+    const results: BenchmarkEngineResult[] = []
+    for (const engine of engines) {
+      const left = deps.totalTimeoutMs - (deps.now() - started)
+      const model = engine === 'whisper' ? deps.whisperModel() : 'parakeet-ultra'
+      if (left <= 0) { results.push({ engine, model, ran: false, skipped: 'total_timeout', peakRssBytes: null }); continue }
+      // A recording that started during the run stops it: the live decoders come first.
+      if (deps.recordingLive()) throw new BenchmarkRefusedError(409, 'recording_live', 'A recording started. Run the check after it is saved.')
+      const budget = Math.min(deps.engineTimeoutMs, left)
+      const which = budget < deps.engineTimeoutMs ? 'total_timeout' as const : 'timeout' as const
+      results.push(engine === 'whisper' ? await runWhisper(audio, audioSeconds, model, budget, which, deps) : await runParakeet(audio, audioSeconds, budget, which, deps))
+    }
+    return { audioSeconds, results }
+  } finally {
+    running = false
+  }
+}
+
+/** One line, single spaces: Control tokenizes for its word error rate. */
+const oneLine = (text: string) => text.replace(/\s+/g, ' ').trim()
+const rtfOf = (ms: number, seconds: number) => seconds > 0 ? Math.round((ms / 1000 / seconds) * 1000) / 1000 : 0
+
+async function runWhisper(audio: Buffer, seconds: number, model: string, budget: number, which: 'timeout' | 'total_timeout', deps: BenchmarkDeps): Promise<BenchmarkEngineResult> {
+  // The live worker is shared and always resident, so its peak is not this decode's.
+  const base = { engine: 'whisper' as const, model, peakRssBytes: null }
+  if (!deps.whisperPresent()) return { ...base, ran: false, skipped: 'not_installed' }
+  const ctl = new AbortController()
+  const t0 = deps.now()
+  try {
+    const r = await within(deps.whisper(audio, ctl.signal), budget, which, ctl)
+    const elapsedMs = Math.round(deps.now() - t0)
+    return { ...base, ran: true, elapsedMs, rtf: rtfOf(elapsedMs, seconds), text: oneLine(r.text) }
+  } catch (error) {
+    if (error instanceof Timeout) return { ...base, ran: false, skipped: error.which }
+    return { ...base, ran: false, skipped: 'unavailable', error: error instanceof Error ? error.message.slice(0, 200) : String(error) }
+  }
+}
+
+async function runParakeet(audio: Buffer, seconds: number, budget: number, which: 'timeout' | 'total_timeout', deps: BenchmarkDeps): Promise<BenchmarkEngineResult> {
+  const base = { engine: 'parakeet-ultra' as const, model: 'parakeet-ultra', peakRssBytes: null as number | null }
+  if (!deps.parakeetInstalled()) return { ...base, ran: false, skipped: 'not_installed' }
+  const ctl = new AbortController()
+  const t0 = deps.now()
+  let warmupMs: number | undefined
+  try {
+    if (!deps.parakeetWarm()) {
+      const ok = await within(deps.warmParakeet(), Math.min(budget, FIRST_LOAD_TIMEOUT_MS), which, ctl)
+      warmupMs = Math.round(deps.now() - t0)
+      if (!ok) return { ...base, ran: false, skipped: 'unavailable', warmupMs, error: 'Parakeet did not warm up on this Mac.' }
+    }
+    const left = budget - (deps.now() - t0)
+    if (left <= 0) return { ...base, ran: false, skipped: which, ...(warmupMs !== undefined ? { warmupMs } : {}) }
+    let peak: number | null = null
+    let sampler: ReturnType<typeof setInterval> | null = null
+    const sample = (pid: number) => { void deps.rss(pid).then(v => { if (v !== null && (peak === null || v > peak)) peak = v }) }
+    const onSpawn = (pid: number) => { sample(pid); sampler = setInterval(() => sample(pid), 50); sampler.unref?.() }
+    const t1 = deps.now()
+    try {
+      const r = await within(deps.parakeet(audio, Math.min(left, parakeetDictationTimeoutMs(audio) * 4), onSpawn, ctl.signal), left, which, ctl)
+      const elapsedMs = Math.round(deps.now() - t1)
+      return { ...base, ran: true, elapsedMs, rtf: rtfOf(elapsedMs, seconds), peakRssBytes: peak, ...(warmupMs !== undefined ? { warmupMs } : {}), text: oneLine(r.text) }
+    } finally {
+      if (sampler) clearInterval(sampler)
+    }
+  } catch (error) {
+    if (error instanceof Timeout) return { ...base, ran: false, skipped: error.which, ...(warmupMs !== undefined ? { warmupMs } : {}) }
+    const busy = (error as { reason?: string })?.reason === 'busy'
+    return { ...base, ran: false, skipped: busy ? 'busy' : 'unavailable', ...(warmupMs !== undefined ? { warmupMs } : {}), error: error instanceof Error ? error.message.slice(0, 200) : String(error) }
+  }
+}

package/server/lib/dictation-stt.ts

@@ -15,11 +15,13 @@
 import { transcribeParakeet, ParakeetError } from './parakeet.js'
 import { asrFrontEnd } from './stt-live.js'
 import {
-  currentSttCapabilities, ensurePreviewWarm, noteParakeetDictationHit, noteParakeetDictationMiss,
+  currentSttCapabilities, ensurePreviewWarm, installCliKnown, noteParakeetDictationHit, noteParakeetDictationMiss,
   PARAKEET_PREVIEW_TIMEOUT_MS, PREVIEW_PARAKEET_MODEL,
 } from './stt-runtime.js'
+import { getWhisperHealth } from './whisper-local.js'
+import { parakeetInstallRunning } from './parakeet.js'
 import {
-  dictationPlan, readSttSettings, type DictationPlan, type DictationSlot, type FrontEndId,
+  desktopDictationPlan, dictationPlan, readSttSettings, type DesktopDictationPlan, type DictationPlan, type DictationSlot, type FrontEndId,
 } from './stt-settings.js'
 
 /** The plan for a dictation decode starting now. A Parakeet selection that is
@@ -37,6 +39,63 @@ export function currentDictationPlan(slot: DictationSlot): DictationPlan {
   return plan
 }
 
+/** 6.74.0: the plan for a Mac dictation decode starting now (its own setting, not the
+ *  Preview model). A Parakeet that is installed but cold starts warming here. */
+export function currentDesktopDictationPlan(slot: DictationSlot): DesktopDictationPlan {
+  try {
+    const plan = desktopDictationPlan(slot, readSttSettings(), currentSttCapabilities())
+    if (plan.reason === 'parakeet_warming' || plan.reason === 'parakeet_warm_failed') ensurePreviewWarm()
+    return plan
+  } catch (error) {
+    console.warn(`[stt] Mac dictation settings unreadable, using Whisper: ${error instanceof Error ? error.message : error}`)
+    return { slot, engine: 'whisper', reason: null, frontEnd: 'highpass', key: slot === 'final' ? 'final:large-v3' : `${slot}:turbo`, setting: 'auto', whisperAllowed: true }
+  }
+}
+
+/** The one action a Mac dictation failure offers (see the contract). */
+export type DesktopDictationAction = 'install_parakeet' | 'use_whisper' | 'retry_when_warm' | 'open_transcription_settings'
+export interface DesktopFailureHint { action: DesktopDictationAction; retryable: boolean; detail: string }
+export interface DesktopFailureFacts {
+  /** no_local_engine: nothing local could run. parakeet_unavailable: the setting is parakeet-ultra. */
+  kind: 'no_local_engine' | 'parakeet_unavailable'
+  /** The Parakeet reason code (plan or decode), when there is one. */
+  parakeetReason: string | null
+  parakeetInstallable: boolean
+  whisperStarting: boolean
+  whisperPresent: boolean
+}
+
+/** Pure. Retry is offered only when waiting can make it succeed. */
+export function desktopFailureHint(f: DesktopFailureFacts): DesktopFailureHint {
+  const waiting = f.parakeetReason === 'parakeet_warming' || f.parakeetReason === 'parakeet_busy'
+  if (f.kind === 'parakeet_unavailable') {
+    const detail = f.parakeetReason ?? 'parakeet_failed'
+    if (detail === 'parakeet_not_installed') return { action: f.parakeetInstallable ? 'install_parakeet' : 'use_whisper', retryable: false, detail }
+    if (waiting) return { action: 'retry_when_warm', retryable: true, detail }
+    return { action: 'use_whisper', retryable: false, detail }
+  }
+  if (f.whisperStarting) return { action: 'retry_when_warm', retryable: true, detail: 'whisper_starting' }
+  const detail = f.whisperPresent ? 'whisper_unavailable' : 'whisper_missing'
+  if (waiting) return { action: 'retry_when_warm', retryable: true, detail }
+  if (f.parakeetReason === 'parakeet_not_installed' && f.parakeetInstallable) return { action: 'install_parakeet', retryable: false, detail }
+  return { action: 'open_transcription_settings', retryable: false, detail }
+}
+
+/** Production facts for desktopFailureHint. Never throws. */
+export function currentDesktopFailureHint(kind: DesktopFailureFacts['kind'], parakeetReason: string | null): DesktopFailureHint {
+  let whisperStarting = false, whisperPresent = true, parakeetInstallable = false
+  try {
+    const h = getWhisperHealth()
+    whisperStarting = h.restarting || h.startupState === 'preflight' || h.startupState === 'loading'
+    whisperPresent = h.serverConfigured
+  } catch { /* unknown: treat as present and not starting */ }
+  try {
+    const installing = parakeetInstallRunning()
+    parakeetInstallable = installing || (process.platform === 'darwin' && process.arch === 'arm64' && installCliKnown().known === true)
+  } catch { /* not installable */ }
+  return desktopFailureHint({ kind, parakeetReason, parakeetInstallable, whisperStarting, whisperPresent })
+}
+
 /** Parakeet reads 16 kHz mono PCM16 WAV. The browser recorder posts WebM, which stays on Whisper. */
 export function isPcm16kMonoWav(audio: Buffer): boolean {
   if (audio.length < 44 || audio.toString('ascii', 0, 4) !== 'RIFF' || audio.toString('ascii', 8, 12) !== 'WAVE') return false

package/server/lib/parakeet-cli-trust.ts

@@ -0,0 +1,262 @@
+// 6.74.0: trust for a fluidaudiocli that COS Control ships signed (its Contents/Helpers).
+//
+// FluidAudio publishes no binary for v0.17.4, so COS Control builds it from the pinned
+// source tag and signs it with the COS Developer ID. That build cannot match the SHA-256
+// pin (parakeet-manifest.ts) because the signature is part of the bytes, so it is trusted
+// on three proofs instead, all required:
+//
+//   1. `codesign --verify --strict` passes, and passes again against the requirement
+//      that the leaf certificate chains to Apple and names the COS team (a self-signed
+//      certificate can claim any team name; `anchor apple generic` rules that out).
+//   2. The TeamIdentifier codesign reports is COS_TEAM_ID.
+//   3. The codesign Identifier, and the CFBundleIdentifier of the Info.plist embedded in
+//      the binary, are both CLI_IDENTIFIER.
+//   4. That embedded Info.plist is bound by the signature (`Info.plist entries=`) and its
+//      CFBundleShortVersionString is 0.17.4. The upstream 0.17.4 CLI has no version
+//      command, so the binary is never run to ask.
+//
+// The hand-placed SHA-256 pinned copy (parakeet.ts isPinnedCli) is unchanged.
+
+import { execFile } from 'node:child_process'
+import { createHash } from 'node:crypto'
+import { constants as fsConstants, createReadStream, fstatSync, openSync, readSync, closeSync, statSync } from 'node:fs'
+import { homedir } from 'node:os'
+import { basename, join } from 'node:path'
+import { pipeline } from 'node:stream/promises'
+import { Transform } from 'node:stream'
+import { PARAKEET_CLI } from './parakeet-manifest.js'
+
+/** The COS Developer ID team (read from /Applications/COS Control.app with codesign -dv, 2026-10-16). */
+export const COS_TEAM_ID = 'NV3X46LLCR'
+export const CODESIGN = '/usr/bin/codesign'
+export const TRUST_REQUIREMENT = `=anchor apple generic and certificate leaf[subject.OU] = "${COS_TEAM_ID}"`
+/** The codesign identifier and embedded CFBundleIdentifier of COS Control's build (agreed with Control). */
+export const CLI_IDENTIFIER = 'com.gotcos.control.fluidaudiocli'
+
+export type CliTrustReason = 'missing' | 'unsigned' | 'signature_invalid' | 'wrong_team' | 'wrong_identifier' | 'wrong_version'
+
+export type CliTrust =
+  | { trusted: true; trust: 'developer-id'; path: string; teamId: string; version: string; versionSource: 'info-plist'; sha256: string; size: number }
+  | { trusted: false; path: string; reason: CliTrustReason; detail: string }
+
+export interface CliTrustDeps {
+  /** codesign -dv: what it prints (stderr), and its exit code. */
+  display: (path: string) => Promise<{ code: number; output: string }>
+  /** codesign --verify --strict [-R requirement]. */
+  verify: (path: string, requirement?: string) => Promise<{ code: number; output: string }>
+  /** The Info.plist embedded in the Mach-O, or null. */
+  embeddedPlist: (path: string) => string | null
+  sha256: (path: string) => Promise<string>
+}
+
+function run(command: string, args: string[], timeoutMs: number): Promise<{ code: number; output: string }> {
+  return new Promise(resolve => {
+    execFile(command, args, { timeout: timeoutMs, maxBuffer: 256 * 1024, env: { PATH: '/usr/bin:/bin' } }, (error, stdout, stderr) => {
+      const code = error ? (typeof (error as { code?: unknown }).code === 'number' ? (error as { code: number }).code : 1) : 0
+      resolve({ code, output: `${stdout ?? ''}${stderr ?? ''}` })
+    })
+  })
+}
+
+async function sha256File(path: string): Promise<string> {
+  const hash = createHash('sha256')
+  await pipeline(createReadStream(path), new Transform({ transform(chunk, _e, cb) { hash.update(chunk); cb(null) } }))
+  return hash.digest('hex')
+}
+
+export const defaultCliTrustDeps: CliTrustDeps = {
+  display: path => run(CODESIGN, ['-dv', path], 10_000),
+  verify: (path, requirement) => run(CODESIGN, ['--verify', '--strict', ...(requirement ? ['-R', requirement] : []), path], 15_000),
+  embeddedPlist: path => readEmbeddedInfoPlist(path),
+  sha256: sha256File,
+}
+
+// ── Mach-O __TEXT,__info_plist ────────────────────────────────────────────────
+
+const MH_MAGIC_64 = 0xfeedfacf
+const FAT_MAGIC = 0xcafebabe
+const LC_SEGMENT_64 = 0x19
+const CPU_TYPE_ARM64 = 0x0100000c
+
+function readAt(fd: number, offset: number, length: number): Buffer {
+  const buf = Buffer.alloc(length)
+  const n = readSync(fd, buf, 0, length, offset)
+  return buf.subarray(0, n)
+}
+
+function cstr(buf: Buffer, start: number): string {
+  const raw = buf.subarray(start, start + 16)
+  const end = raw.indexOf(0)
+  return raw.subarray(0, end < 0 ? 16 : end).toString('ascii')
+}
+
+/** The __TEXT,__info_plist section of a thin 64-bit or fat Mach-O (arm64 slice), or null. */
+export function readEmbeddedInfoPlist(path: string): string | null {
+  let fd: number
+  // Non-blocking and no-follow: the path can come from a client, and a FIFO would
+  // block this synchronous open, and with it the whole server (hazard-invariants.test.ts).
+  try { fd = openSync(path, fsConstants.O_RDONLY | fsConstants.O_NONBLOCK | fsConstants.O_NOFOLLOW) } catch { return null }
+  try { if (!fstatSync(fd).isFile()) { closeSync(fd); return null } } catch { closeSync(fd); return null }
+  try {
+    let base = 0
+    const head = readAt(fd, 0, 8)
+    if (head.length < 8) return null
+    if (head.readUInt32BE(0) === FAT_MAGIC) {
+      const count = head.readUInt32BE(4)
+      if (count > 16) return null
+      const arches = readAt(fd, 8, count * 20)
+      base = -1
+      for (let i = 0; i < count; i++) {
+        if (arches.readUInt32BE(i * 20) === CPU_TYPE_ARM64) { base = arches.readUInt32BE(i * 20 + 8); break }
+      }
+      if (base < 0) return null
+    }
+    const header = readAt(fd, base, 32)
+    if (header.length < 32 || header.readUInt32LE(0) !== MH_MAGIC_64) return null
+    const ncmds = header.readUInt32LE(16)
+    const sizeofcmds = header.readUInt32LE(20)
+    if (sizeofcmds > 4 * 1024 * 1024) return null
+    const cmds = readAt(fd, base + 32, sizeofcmds)
+    let off = 0
+    for (let i = 0; i < ncmds && off + 8 <= cmds.length; i++) {
+      const cmd = cmds.readUInt32LE(off)
+      const cmdsize = cmds.readUInt32LE(off + 4)
+      if (cmdsize < 8) return null
+      if (cmd === LC_SEGMENT_64 && cstr(cmds, off + 8) === '__TEXT') {
+        const nsects = cmds.readUInt32LE(off + 64)
+        for (let s = 0; s < nsects; s++) {
+          const sec = off + 72 + s * 80
+          if (sec + 80 > cmds.length) return null
+          if (cstr(cmds, sec) !== '__info_plist') continue
+          const size = Number(cmds.readBigUInt64LE(sec + 40))
+          const offset = cmds.readUInt32LE(sec + 48)
+          if (size <= 0 || size > 64 * 1024) return null
+          return readAt(fd, base + offset, size).toString('utf8').replace(/\0+$/, '')
+        }
+      }
+      off += cmdsize
+    }
+    return null
+  } catch { return null } finally { closeSync(fd) }
+}
+
+function plistString(xml: string, key: string): string | null {
+  const m = new RegExp(`<key>${key}</key>\\s*<string>([^<]{1,128})</string>`).exec(xml)
+  return m ? m[1].trim() : null
+}
+/** CFBundleShortVersionString from an XML plist. */
+export function plistVersion(xml: string): string | null { return plistString(xml, 'CFBundleShortVersionString') }
+export function plistIdentifier(xml: string): string | null { return plistString(xml, 'CFBundleIdentifier') }
+
+/** 0.17.4 as a whole token, so 0.17.40 or 10.17.4 never pass. */
+export function versionMatches(text: string, want: string = PARAKEET_CLI.version): boolean {
+  const escaped = want.replace(/\./g, '\\.')
+  return new RegExp(`(^|[^0-9.])v?${escaped}(?![0-9]|\\.[0-9])`).test(text)
+}
+
+export function parseCodesignDisplay(output: string): { teamId: string | null; identifier: string | null; adhoc: boolean; unsigned: boolean; plistBound: boolean } {
+  const team = /^TeamIdentifier=(.+)$/m.exec(output)?.[1]?.trim() ?? null
+  return {
+    teamId: team && team !== 'not set' ? team : null,
+    identifier: /^Identifier=(.+)$/m.exec(output)?.[1]?.trim() ?? null,
+    adhoc: /^Signature=adhoc$/m.test(output) || /flags=0x[0-9a-f]*\([^)]*adhoc/.test(output),
+    unsigned: /code object is not signed at all/i.test(output),
+    plistBound: /^Info\.plist entries=\d+/m.test(output),
+  }
+}
+
+/** Every proof, in order; the first that fails names the reason. Never throws. */
+export async function checkDeveloperIdCli(path: string, deps: CliTrustDeps = defaultCliTrustDeps): Promise<CliTrust> {
+  const no = (reason: CliTrustReason, detail: string): CliTrust => ({ trusted: false, path, reason, detail })
+  let size: number
+  try { const st = statSync(path); if (!st.isFile()) return no('missing', 'not a file'); size = st.size } catch { return no('missing', 'not found') }
+  try {
+    const shown = await deps.display(path)
+    const d = parseCodesignDisplay(shown.output)
+    if (d.unsigned || shown.code !== 0) return no('unsigned', 'the speech tool is not signed')
+    if (d.adhoc || !d.teamId) return no('unsigned', 'the speech tool has no Developer ID signature')
+    const strict = await deps.verify(path)
+    if (strict.code !== 0) return no('signature_invalid', strict.output.trim().split('\n').slice(-1)[0]?.slice(0, 200) || 'the signature does not verify')
+    if (d.teamId !== COS_TEAM_ID) return no('wrong_team', `signed by team ${d.teamId}`)
+    const anchored = await deps.verify(path, TRUST_REQUIREMENT)
+    if (anchored.code !== 0) return no('wrong_team', 'the signature does not chain to Apple for the COS team')
+    if (d.identifier !== CLI_IDENTIFIER) return no('wrong_identifier', `signed as ${d.identifier ?? 'no identifier'}`)
+    // Only a plist the signature binds counts; the binary is never run to ask its version.
+    const plist = d.plistBound ? deps.embeddedPlist(path) : null
+    if (!plist) return no('wrong_version', 'no signed Info.plist in the speech tool')
+    const bundleId = plistIdentifier(plist)
+    if (bundleId !== CLI_IDENTIFIER) return no('wrong_identifier', `its Info.plist names ${bundleId ?? 'no identifier'}`)
+    const named = plistVersion(plist)
+    if (!named || !versionMatches(named) || named.replace(/^v/, '') !== PARAKEET_CLI.version) return no('wrong_version', `version ${named ?? 'unknown'}, not FluidAudio ${PARAKEET_CLI.version}`)
+    const sha256 = await deps.sha256(path)
+    // The bytes hashed must be the bytes checked.
+    if (statSync(path).size !== size) return no('signature_invalid', 'the file changed while it was checked')
+    return { trusted: true, trust: 'developer-id', path, teamId: COS_TEAM_ID, version: PARAKEET_CLI.version, versionSource: 'info-plist', sha256, size }
+  } catch (error) {
+    return no('signature_invalid', error instanceof Error ? error.message.slice(0, 200) : String(error))
+  }
+}
+
+// ── Where COS Control's copy is, and a per-process cache for GET ──────────────
+
+const HELPER_REL = join('COS Control.app', 'Contents', 'Helpers', 'fluidaudiocli')
+
+/** COS Control in /Applications or ~/Applications, plus any path Control registered. */
+export function controlCliCandidates(home: string = homedir()): string[] {
+  return [...offered, join(applicationsRoot, HELPER_REL), join(home, 'Applications', HELPER_REL)]
+}
+let applicationsRoot = '/Applications'
+/** Tests only: keep the real /Applications out of a test's view. */
+export function __setApplicationsRootForTests(root: string | null): void { applicationsRoot = root ?? '/Applications' }
+
+const offered: string[] = []
+/** An absolute path whose file name is fluidaudiocli. Anything else is never checked or run. */
+export function isCliPathShape(path: unknown): path is string {
+  return typeof path === 'string' && path.startsWith('/') && path.length <= 1024 && !path.includes('\0') && basename(path) === 'fluidaudiocli'
+}
+/** Control tells the server where its bundled CLI is (POST /api/stt-settings/parakeet/cli). */
+export function offerControlCli(path: string): void {
+  if (!isCliPathShape(path)) return
+  if (!offered.includes(path)) offered.unshift(path)
+  if (offered.length > 4) offered.length = 4
+}
+
+const cache = new Map<string, CliTrust>()
+const pending = new Map<string, Promise<CliTrust>>()
+function cacheKey(path: string): string | null {
+  try { const st = statSync(path); return st.isFile() ? `${path}\0${st.size}\0${st.mtimeMs}\0${st.ino}` : null } catch { return null }
+}
+
+/** Check (once per path, size, mtime and inode) and remember. */
+export function trustCli(path: string, deps: CliTrustDeps = defaultCliTrustDeps): Promise<CliTrust> {
+  const key = cacheKey(path)
+  if (!key) return Promise.resolve({ trusted: false, path, reason: 'missing', detail: 'not found' })
+  const known = cache.get(key)
+  if (known) return Promise.resolve(known)
+  const running = pending.get(key)
+  if (running) return running
+  const job = checkDeveloperIdCli(path, deps).then(r => { cache.set(key, r); return r }).finally(() => pending.delete(key))
+  pending.set(key, job)
+  return job
+}
+
+/** Synchronous, for GET: the known result for this file, null while unchecked (a check starts). */
+export function knownCliTrust(path: string): CliTrust | null {
+  const key = cacheKey(path)
+  if (!key) return { trusted: false, path, reason: 'missing', detail: 'not found' }
+  const known = cache.get(key)
+  if (known) return known
+  void trustCli(path)
+  return null
+}
+
+/** The first trusted candidate, or null. */
+export async function findTrustedCli(candidates: string[] = controlCliCandidates(), deps?: CliTrustDeps): Promise<Extract<CliTrust, { trusted: true }> | null> {
+  for (const c of candidates) {
+    const r = await trustCli(c, deps)
+    if (r.trusted) return r
+  }
+  return null
+}
+
+export function __resetCliTrustForTests(): void { cache.clear(); pending.clear(); offered.length = 0; applicationsRoot = '/Applications' }