@gotcos/glasses-server 6.73.14 → 6.74.0

package/server/lib/parakeet.ts

@@ -20,7 +20,7 @@ import { execFileSync, spawn as nodeSpawn, type ChildProcess, type SpawnOptions
 import { createHash, randomBytes } from 'node:crypto'
 import {
   chmodSync, copyFileSync, createReadStream, createWriteStream, existsSync, mkdirSync, mkdtempSync,
-  readFileSync, readdirSync, realpathSync, renameSync, rmSync, statSync, writeFileSync,
+  readFileSync, readdirSync, realpathSync, renameSync, rmSync, statSync, statfsSync, writeFileSync,
 } from 'node:fs'
 import { homedir, setPriority, tmpdir } from 'node:os'
 import { dirname, join, resolve } from 'node:path'
@@ -29,6 +29,7 @@ import { Readable, Transform } from 'node:stream'
 import { durableAtomicWriteFileSync } from './atomic-fs.js'
 import { dataPath } from './data-dir.js'
 import { PARAKEET_CLI, PARAKEET_MODELS, type PinnedModel } from './parakeet-manifest.js'
+import { checkDeveloperIdCli, controlCliCandidates, COS_TEAM_ID, findTrustedCli, isCliPathShape, type CliTrustDeps, type CliTrustReason } from './parakeet-cli-trust.js'
 import type { HypWord } from './stt-resolver.js'
 
 export type ParakeetModelId = 'parakeet-ultra'
@@ -57,18 +58,23 @@ function pinned(id: ParakeetModelId): PinnedModel {
 // ── Install state ─────────────────────────────────────────────────────────────
 
 export type InstallPhase = 'idle' | 'downloading' | 'verifying' | 'installed' | 'failed'
+/** 6.74.0: why an install failed, for a client that picks the action from a code. */
+export type InstallErrorCode = 'cancelled' | 'insufficient_disk' | 'sha_mismatch' | 'download_failed' | 'stalled' | 'cli_untrusted' | 'cli_missing' | 'failed'
 export interface InstallProgress {
   state: InstallPhase
   bytesDone: number
   bytesTotal: number
   error: string | null
+  errorCode?: InstallErrorCode | null
   /** Where the bytes came from: files copied from a verified local copy, and files downloaded. */
   source?: { filesLocal: number; filesDownloaded: number; localSources: string[] }
 }
 
 export interface InstallReceipt {
   schema: 1
-  cli: { version: string; sha256: string }
+  /** trust (6.74.0): 'sha256' (absent before 6.74.0) is the pinned upstream bytes;
+   *  'developer-id' is COS Control's signed build, its own hash and size recorded at install. */
+  cli: { version: string; sha256: string; size?: number; trust?: 'sha256' | 'developer-id'; teamId?: string }
   models: Array<{ id: string; revision: string; bytes: number }>
   bytes: number
   installedAt: string
@@ -94,7 +100,7 @@ export function parakeetInstalled(now = Date.now()): { installed: boolean; bytes
   try {
     const receipt = JSON.parse(readFileSync(receiptPath(), 'utf8')) as InstallReceipt
     const sizeOk = (path: string, size: number) => { try { return statSync(path).size === size } catch { return false } }
-    const cliOk = receipt?.schema === 1 && receipt.cli?.sha256 === PARAKEET_CLI.sha256 && sizeOk(parakeetCliPath(), PARAKEET_CLI.size)
+    const cliOk = receipt?.schema === 1 && receiptCliOk(receipt.cli, sizeOk)
     const modelsOk = PARAKEET_MODELS.every(m =>
       receipt.models?.some(r => r.id === m.id && r.revision === m.revision)
       && m.files.every(f => sizeOk(join(parakeetModelDir(m.id as ParakeetModelId), f.path), f.size)))
@@ -104,6 +110,26 @@ export function parakeetInstalled(now = Date.now()): { installed: boolean; bytes
   return value
 }
 
+/** The receipt's CLI is one this server trusts, and the installed file has its size. */
+function receiptCliOk(cli: InstallReceipt['cli'] | undefined, sizeOk: (path: string, size: number) => boolean): boolean {
+  if (!cli || cli.version !== PARAKEET_CLI.version) return false
+  if (cli.trust === 'developer-id') {
+    return cli.teamId === COS_TEAM_ID && typeof cli.sha256 === 'string' && /^[0-9a-f]{64}$/.test(cli.sha256)
+      && typeof cli.size === 'number' && sizeOk(parakeetCliPath(), cli.size)
+  }
+  return cli.sha256 === PARAKEET_CLI.sha256 && sizeOk(parakeetCliPath(), PARAKEET_CLI.size)
+}
+
+function readReceipt(): InstallReceipt | null {
+  try { return JSON.parse(readFileSync(receiptPath(), 'utf8')) as InstallReceipt } catch { return null }
+}
+
+/** 6.74.0: how the installed CLI was trusted, for GET. */
+export function installedCliTrust(): 'sha256' | 'developer-id' | null {
+  const cli = readReceipt()?.cli
+  return cli ? cli.trust ?? 'sha256' : null
+}
+
 export function resetParakeetInstallCache(): void { installedCache = null; cliHashCache.clear() }
 
 async function sha256File(path: string): Promise<string> {
@@ -185,7 +211,32 @@ function modelDirCandidates(model: PinnedModel, sources: string[]): string[] {
 }
 
 export class ParakeetInstallError extends Error {
-  constructor(message: string) { super(message); this.name = 'ParakeetInstallError' }
+  constructor(message: string, readonly code: InstallErrorCode = 'failed') { super(message); this.name = 'ParakeetInstallError' }
+}
+
+/** 6.74.0: an install needs this much free space where it installs (654 MB of model,
+ *  the CLI, a staging copy of each file before the swap, and headroom). */
+export const INSTALL_MIN_FREE_BYTES = 1_500_000_000
+
+/** Free bytes on the volume holding `dir` (its nearest existing ancestor), or null when unknown. */
+export function freeBytesAt(dir: string): number | null {
+  let probe = resolve(dir)
+  for (let i = 0; i < 64; i++) {
+    if (existsSync(probe)) {
+      try { const st = statfsSync(probe); return Number(st.bavail) * Number(st.bsize) } catch { return null }
+    }
+    const up = dirname(probe)
+    if (up === probe) return null
+    probe = up
+  }
+  return null
+}
+
+/** The disk precheck the install route and the installer share. */
+export function parakeetDiskCheck(freeBytes: (dir: string) => number | null = freeBytesAt, required = INSTALL_MIN_FREE_BYTES): { ok: boolean; freeBytes: number | null; requiredBytes: number } {
+  const free = freeBytes(parakeetRoot())
+  // Unknown free space does not block: the per-file writes still fail plainly on a full disk.
+  return { ok: free === null || free >= required, freeBytes: free, requiredBytes: required }
 }
 
 type FetchLike = (url: string, init?: { signal?: AbortSignal }) => Promise<{ ok: boolean; status: number; body: ReadableStream<Uint8Array> | null }>
@@ -201,6 +252,12 @@ export interface InstallOptions {
   cliCandidates?: string[]
   fetchImpl?: FetchLike
   idleTimeoutMs?: number
+  /** 6.74.0, tests: codesign and version probes for a Developer ID CLI. */
+  trustDeps?: CliTrustDeps
+  /** 6.74.0, tests: where COS Control's signed CLI may be (defaults to /Applications and ~/Applications). */
+  controlCliCandidates?: string[]
+  /** 6.74.0, tests: free space probe. */
+  freeBytes?: (dir: string) => number | null
 }
 
 /** Start the install, or join the one already running. */
@@ -216,27 +273,53 @@ export function parakeetInstallRunning(): boolean { return installing !== null }
 /** Stop a running install; nothing partial is kept. */
 export function cancelParakeetInstall(): boolean {
   if (!installAbort) return false
-  installAbort.abort(new ParakeetInstallError('The install was cancelled.'))
+  installAbort.abort(new ParakeetInstallError('The install was cancelled.', 'cancelled'))
   return true
 }
 
 async function runInstall(options: InstallOptions, signal: AbortSignal): Promise<void> {
   const root = parakeetRoot()
   const localSources = [...(options.localSources ?? []), ...defaultLocalSources()]
-  progress = { state: 'verifying', bytesDone: 0, bytesTotal: TOTAL_BYTES, error: null, source: { filesLocal: 0, filesDownloaded: 0, localSources: [] } }
-  mkdirSync(root, { recursive: true, mode: 0o700 })
-  const staging = join(root, `.staging-${randomBytes(6).toString('hex')}`)
-  mkdirSync(join(staging, 'bin'), { recursive: true, mode: 0o700 })
+  progress = { state: 'verifying', bytesDone: 0, bytesTotal: TOTAL_BYTES, error: null, errorCode: null, source: { filesLocal: 0, filesDownloaded: 0, localSources: [] } }
   const usedSources = new Set<string>()
+  let staging: string | null = null
   try {
-    // 1. The CLI. FluidAudio publishes no binary, so a pinned local copy is the only source.
+    // 0. Disk precheck (6.74.0), before anything is written.
+    const disk = parakeetDiskCheck(options.freeBytes)
+    if (!disk.ok) {
+      throw new ParakeetInstallError(`Parakeet needs ${formatGb(disk.requiredBytes)} free on this Mac; ${formatGb(disk.freeBytes ?? 0)} is free. Free some space, then install again. Whisper keeps working.`, 'insufficient_disk')
+    }
+    mkdirSync(root, { recursive: true, mode: 0o700 })
+    staging = join(root, `.staging-${randomBytes(6).toString('hex')}`)
+    mkdirSync(join(staging, 'bin'), { recursive: true, mode: 0o700 })
+
+    // 1. The CLI. FluidAudio publishes no binary: a SHA-256 pinned local copy, or
+    //    (6.74.0) the build COS Control ships signed with the COS Developer ID.
     const cliTarget = join(staging, 'bin', 'fluidaudiocli')
     const cli = await findPinnedCli([...(options.cliCandidates ?? []), ...(options.localSources ?? []).map(src => fileSize(src) !== null ? src : join(src, 'fluidaudiocli')), ...defaultCliCandidates()])
-    if (!cli) {
-      throw new ParakeetInstallError(`FluidAudio CLI ${PARAKEET_CLI.version} is not on this Mac. It is the same tool speaker separation uses; put it at ~/.cos-glasses/bin/fluidaudiocli, then install again.`)
+    let receiptCli: InstallReceipt['cli']
+    if (cli) {
+      copyFileSync(cli, cliTarget)
+      if (await sha256File(cliTarget) !== PARAKEET_CLI.sha256) throw new ParakeetInstallError('The FluidAudio CLI changed while it was being copied. Try again.')
+      receiptCli = { version: PARAKEET_CLI.version, sha256: PARAKEET_CLI.sha256, size: PARAKEET_CLI.size, trust: 'sha256' }
+    } else {
+      const signedCandidates = [...new Set([...(options.cliCandidates ?? []).filter(isCliPathShape), ...(options.controlCliCandidates ?? controlCliCandidates())])]
+      const signed = await findTrustedCli(signedCandidates, options.trustDeps)
+      if (!signed) {
+        const seen = signedCandidates.find(path => fileSize(path) !== null)
+        if (seen) {
+          const why = await checkDeveloperIdCli(seen, options.trustDeps)
+          const reason: CliTrustReason = why.trusted ? 'signature_invalid' : why.reason
+          throw new ParakeetInstallError(`The speech tool in COS Control did not pass its check (${reason}). Reinstall COS Control, then install again.`, 'cli_untrusted')
+        }
+        throw new ParakeetInstallError(`The speech tool Parakeet needs is not on this Mac. Update COS Control, which includes it, then install again.`, 'cli_missing')
+      }
+      copyFileSync(signed.path, cliTarget)
+      // Prove the copy, not only the source: the installed bytes must be signed and unchanged.
+      const copy = await checkDeveloperIdCli(cliTarget, options.trustDeps)
+      if (!copy.trusted || copy.sha256 !== signed.sha256) throw new ParakeetInstallError('The speech tool changed while it was being copied. Try again.', 'cli_untrusted')
+      receiptCli = { version: PARAKEET_CLI.version, sha256: copy.sha256, size: copy.size, trust: 'developer-id', teamId: COS_TEAM_ID }
     }
-    copyFileSync(cli, cliTarget)
-    if (await sha256File(cliTarget) !== PARAKEET_CLI.sha256) throw new ParakeetInstallError('The FluidAudio CLI changed while it was being copied. Try again.')
     chmodSync(cliTarget, 0o755)
     progress.bytesDone += PARAKEET_CLI.size
 
@@ -246,7 +329,7 @@ async function runInstall(options: InstallOptions, signal: AbortSignal): Promise
     for (const model of PARAKEET_MODELS) {
       const candidates = modelDirCandidates(model, localSources)
       for (const file of model.files) {
-        if (signal.aborted) throw new ParakeetInstallError('The install was cancelled.')
+        if (signal.aborted) throw new ParakeetInstallError('The install was cancelled.', 'cancelled')
         const target = join(staging, 'models', model.id, file.path)
         mkdirSync(dirname(target), { recursive: true, mode: 0o700 })
         let placed = false
@@ -268,12 +351,12 @@ async function runInstall(options: InstallOptions, signal: AbortSignal): Promise
           const url = `https://huggingface.co/${model.repo}/resolve/${model.revision}/${file.path.split('/').map(encodeURIComponent).join('/')}`
           // One controller per file: user cancel, or no bytes for idleMs.
           const ctl = new AbortController()
-          const onCancel = () => ctl.abort(new ParakeetInstallError('The install was cancelled.'))
+          const onCancel = () => ctl.abort(new ParakeetInstallError('The install was cancelled.', 'cancelled'))
           signal.addEventListener('abort', onCancel, { once: true })
           let idle: ReturnType<typeof setTimeout> | null = null
           const arm = () => {
             if (idle) clearTimeout(idle)
-            idle = setTimeout(() => ctl.abort(new ParakeetInstallError(`The download stalled (no data for ${Math.round(idleMs / 1000)} s). Nothing was installed; try again.`)), idleMs)
+            idle = setTimeout(() => ctl.abort(new ParakeetInstallError(`The download stalled (no data for ${Math.round(idleMs / 1000)} s). Nothing was installed; try again.`, 'stalled')), idleMs)
             idle.unref?.()
           }
           arm()
@@ -281,18 +364,20 @@ async function runInstall(options: InstallOptions, signal: AbortSignal): Promise
           let written = 0
           try {
             const res = await fetchImpl(url, { signal: ctl.signal })
-            if (!res.ok || !res.body) throw new ParakeetInstallError(`Download failed (${res.status}) for ${model.id} ${file.path}.`)
+            if (!res.ok || !res.body) throw new ParakeetInstallError(`Download failed (${res.status}) for ${model.id} ${file.path}.`, 'download_failed')
             const counter = new Transform({ transform(chunk, _e, cb) {
               arm()
               written += chunk.length
-              if (written > file.size) { cb(new ParakeetInstallError(`${model.id} ${file.path} is larger than the pinned size.`)); return }
+              if (written > file.size) { cb(new ParakeetInstallError(`${model.id} ${file.path} is larger than the pinned size.`, 'sha_mismatch')); return }
               progress.bytesDone += chunk.length
               cb(null, chunk)
             } })
             await pipeline(Readable.fromWeb(res.body as any), counter, createWriteStream(partial, { mode: 0o600 }), { signal: ctl.signal })
           } catch (error) {
             const why = ctl.signal.reason
-            throw why instanceof ParakeetInstallError ? why : error
+            if (why instanceof ParakeetInstallError) throw why
+            if (error instanceof ParakeetInstallError) throw error
+            throw new ParakeetInstallError(`Download failed for ${model.id} ${file.path}: ${error instanceof Error ? error.message : String(error)}`, 'download_failed')
           } finally {
             if (idle) clearTimeout(idle)
             signal.removeEventListener('abort', onCancel)
@@ -303,7 +388,7 @@ async function runInstall(options: InstallOptions, signal: AbortSignal): Promise
         }
         progress.state = 'verifying'
         if (fileSize(target) !== file.size || await sha256File(target) !== file.sha256) {
-          throw new ParakeetInstallError(`${model.id} ${file.path} does not match its pinned SHA-256. Nothing was installed.`)
+          throw new ParakeetInstallError(`${model.id} ${file.path} does not match its pinned SHA-256. Nothing was installed.`, 'sha_mismatch')
         }
         progress.bytesDone += file.size
       }
@@ -312,7 +397,7 @@ async function runInstall(options: InstallOptions, signal: AbortSignal): Promise
 
     const receipt: InstallReceipt = {
       schema: 1,
-      cli: { version: PARAKEET_CLI.version, sha256: PARAKEET_CLI.sha256 },
+      cli: receiptCli,
       models: PARAKEET_MODELS.map(m => ({ id: m.id, revision: m.revision, bytes: m.files.reduce((n, f) => n + f.size, 0) })),
       bytes: TOTAL_BYTES,
       installedAt: new Date().toISOString(),
@@ -324,20 +409,23 @@ async function runInstall(options: InstallOptions, signal: AbortSignal): Promise
     const current = currentDir()
     const old = existsSync(current) ? join(root, `.old-${Date.now()}-${randomBytes(3).toString('hex')}`) : null
     if (old) renameSync(current, old)
-    renameSync(staging, current)
+    renameSync(staging!, current)
     if (old) rmSync(old, { recursive: true, force: true })
     mkdirSync(parakeetHome(), { recursive: true, mode: 0o700 })
     resetParakeetInstallCache()
     for (const id of warm.keys()) warm.delete(id)
-    progress = { ...progress, state: 'installed', bytesDone: TOTAL_BYTES, bytesTotal: TOTAL_BYTES, error: null }
+    progress = { ...progress, state: 'installed', bytesDone: TOTAL_BYTES, bytesTotal: TOTAL_BYTES, error: null, errorCode: null }
   } catch (error) {
-    rmSync(staging, { recursive: true, force: true })
+    if (staging) rmSync(staging, { recursive: true, force: true })
     const message = error instanceof ParakeetInstallError ? error.message : `Install failed: ${error instanceof Error ? error.message : String(error)}`
-    progress = { ...progress, state: 'failed', bytesTotal: TOTAL_BYTES, error: message, source: progress.source ? { ...progress.source, localSources: [...usedSources] } : undefined }
-    throw new ParakeetInstallError(message)
+    const code: InstallErrorCode = error instanceof ParakeetInstallError ? error.code : 'failed'
+    progress = { ...progress, state: 'failed', bytesTotal: TOTAL_BYTES, error: message, errorCode: code, source: progress.source ? { ...progress.source, localSources: [...usedSources] } : undefined }
+    throw new ParakeetInstallError(message, code)
   }
 }
 
+function formatGb(bytes: number): string { return `${(bytes / 1e9).toFixed(1)} GB` }
+
 /**
  * Boot: put back an install a crash left mid-swap (no `current`, an `.old-*`
  * present), then remove staging and old directories.
@@ -392,6 +480,8 @@ export interface ParakeetRunOptions {
   spawnImpl?: SpawnLike
   /** Tests only: a different sandbox-exec path. There is no environment override. */
   sandboxExec?: string
+  /** 6.74.0 benchmark: called with the child's pid once it is spawned (peak memory sampling). */
+  onSpawn?: (pid: number) => void
 }
 
 const liveChildren = new Set<ChildProcess>()
@@ -537,12 +627,48 @@ export function transcribeParakeet(wav: Buffer, options: ParakeetRunOptions): Pr
 
 async function runParakeet(wav: Buffer, options: ParakeetRunOptions): Promise<ParakeetResult> {
   // The installed CLI's full hash, once per process (and again if it changes on disk).
-  if (!options.spawnImpl && !(await isPinnedCli(parakeetCliPath()))) {
-    throw new ParakeetError('not_installed', 'the installed FluidAudio CLI no longer matches its pinned SHA-256')
+  if (!options.spawnImpl && !(await installedCliIntact())) {
+    throw new ParakeetError('not_installed', 'the installed FluidAudio CLI no longer matches the hash recorded when it was installed')
   }
   return runParakeetChecked(wav, options)
 }
 
+/**
+ * 6.74.0, for the diarizer's CLI lookup (synchronous, read on health): the GUI-installed
+ * CLI is trusted only when the install is complete and its bytes are known to match the
+ * receipt (the pinned hash, or the Developer ID build's recorded hash). null while that
+ * hash has not been checked in this process; a check starts in the background.
+ */
+export function installedCliTrustedNow(): boolean | null {
+  if (!parakeetInstalled().installed) return false
+  const path = parakeetCliPath()
+  const st = fileStat(path)
+  if (!st) return false
+  const cli = readReceipt()?.cli
+  const key = cli?.trust === 'developer-id'
+    ? `${path}\0${st.size}\0${st.mtimeMs}\0${cli.sha256}`
+    : `${path}\0${st.size}\0${st.mtimeMs}`
+  const known = cliHashCache.get(key)
+  if (known !== undefined) return known
+  void installedCliIntact(path)
+  return null
+}
+
+/** The installed CLI is byte for byte what the install verified: the pinned hash, or
+ *  (6.74.0) the hash of the Developer ID build recorded in the receipt. */
+export async function installedCliIntact(path: string = parakeetCliPath()): Promise<boolean> {
+  const cli = readReceipt()?.cli
+  if (cli?.trust !== 'developer-id') return isPinnedCli(path)
+  const st = fileStat(path)
+  if (!st || st.size !== cli.size || cli.teamId !== COS_TEAM_ID) return false
+  const key = `${path}\0${st.size}\0${st.mtimeMs}\0${cli.sha256}`
+  const known = cliHashCache.get(key)
+  if (known !== undefined) return known
+  const ok = await sha256File(path).then(h => h === cli.sha256, () => false)
+  cliHashCache.set(key, ok)
+  return ok
+}
+
 function runParakeetChecked(wav: Buffer, options: ParakeetRunOptions): Promise<ParakeetResult> {
   const started = Date.now()
   if (!parakeetInstalled().installed) return Promise.reject(new ParakeetError('not_installed', 'Parakeet is not installed'))
@@ -591,6 +717,7 @@ function runParakeetChecked(wav: Buffer, options: ParakeetRunOptions): Promise<P
     options.signal?.addEventListener('abort', onAbort, { once: true })
     liveChildren.add(child)
     child.once('close', () => liveChildren.delete(child))
+    if (child.pid && options.onSpawn) { try { options.onSpawn(child.pid) } catch { /* sampling only */ } }
     if (child.pid && options.lane !== 'preview' && options.lane !== 'interactive') {
       try { setPriority(child.pid, 10) } catch { /* runs at normal priority */ }
     }

package/server/lib/stt-runtime.ts

@@ -11,9 +11,10 @@ import {
 import { transcribeWhisperMeetingPreview } from './whisper-preview.js'
 import { asrFrontEnd } from './stt-live.js'
 import {
-  getInstallProgress, parakeetInstalled, parakeetInstallRunning, parakeetWarmState, pinnedCliKnown,
+  getInstallProgress, installedCliTrust, parakeetInstalled, parakeetInstallRunning, parakeetWarmState, pinnedCliKnown,
   PARAKEET_VERSION_LABEL, transcribeParakeet, warmParakeet, type ParakeetModelId,
 } from './parakeet.js'
+import { controlCliCandidates, knownCliTrust, type CliTrust } from './parakeet-cli-trust.js'
 import {
   effectiveStt, readSttSettings, type EffectiveStt, type FrontEndId, type ParakeetStatus,
   type SttCapabilities,
@@ -36,6 +37,8 @@ export const PREVIEW_BREAKER_MAX_MS = 10 * 60_000
 let recordingLiveProbe: () => boolean = () => false
 export function setRecordingLiveProbe(probe: () => boolean): void { recordingLiveProbe = probe }
 function recordingLive(): boolean { try { return recordingLiveProbe() } catch { return true } }
+/** 6.74.0: the benchmark route refuses while a recording is live. Fails closed. */
+export function isRecordingLive(): boolean { return recordingLive() }
 
 // ── Preview breaker and counters ─────────────────────────────────────────────
 const previewStats = { parakeet: 0, parakeetMisses: 0, turboFallbacks: 0, turbo: 0, nonTurboWithheld: 0, empty: 0 }
@@ -93,32 +96,60 @@ export function currentEffectiveStt(): EffectiveStt {
   return effectiveStt(readSttSettings(), currentSttCapabilities())
 }
 
+/** 6.74.0: which CLI an install would use. A SHA-256 pinned hand copy, else COS Control's
+ *  signed build. true or false once known, null while a check runs (GET never blocks). */
+export function installCliKnown(): { known: boolean | null; trust: 'sha256' | 'developer-id' | null; untrusted: CliTrust | null } {
+  const pinned = pinnedCliKnown()
+  if (pinned === true) return { known: true, trust: 'sha256', untrusted: null }
+  let unknown = pinned === null
+  let untrusted: CliTrust | null = null
+  for (const path of controlCliCandidates()) {
+    const t = knownCliTrust(path)
+    if (t === null) { unknown = true; continue }
+    if (t.trusted) return { known: true, trust: 'developer-id', untrusted: null }
+    if (t.reason !== 'missing' && !untrusted) untrusted = t
+  }
+  return { known: unknown ? null : false, trust: null, untrusted }
+}
+
+const UNTRUSTED_NOTE: Record<string, string> = {
+  unsigned: 'is not signed',
+  signature_invalid: 'has a signature that does not verify',
+  wrong_team: 'is not signed by COS',
+  wrong_version: 'is not the FluidAudio 0.17.4 build Parakeet needs',
+}
+
 export function parakeetStatus(live: boolean): ParakeetStatus {
   const installed = parakeetInstalled()
   const progress = getInstallProgress()
   const running = parakeetInstallRunning()
   const sandbox = existsSync('/usr/bin/sandbox-exec')
   const appleSilicon = process.platform === 'darwin' && process.arch === 'arm64'
-  // A button that can never succeed is never offered: the pinned CLI must be on this Mac.
-  const cli = appleSilicon ? pinnedCliKnown() : false
-  const installable = !installed.installed && !running && sandbox && appleSilicon && cli === true
+  // A button that can never succeed is never offered: a trusted CLI must be on this Mac,
+  // a SHA-256 pinned copy or (6.74.0) the signed one COS Control ships.
+  const cli = appleSilicon ? installCliKnown() : { known: false, trust: null, untrusted: null }
+  const installable = !installed.installed && !running && sandbox && appleSilicon && cli.known === true
   const warm = parakeetWarmState(PREVIEW_PARAKEET_MODEL)
+  const untrustedReason = cli.untrusted && !cli.untrusted.trusted ? cli.untrusted.reason : null
   const note = installed.installed
     ? 'Installed. Runs offline on the Neural Engine.'
     : running
-      ? 'Installing.'
+      ? 'Installing. Dictation uses Whisper until it is ready.'
       : !sandbox || !appleSilicon
         ? 'Parakeet needs an Apple silicon Mac.'
-        : cli === false
-          ? 'Parakeet needs FluidAudio fluidaudiocli 0.17.4 at ~/.cos-glasses/bin (the speaker-separation tool); this Mac does not have that build.'
-          : cli === null
-            ? 'Checking this Mac for the FluidAudio CLI.'
+        : cli.known === false
+          ? untrustedReason
+            ? `The speech tool in COS Control ${UNTRUSTED_NOTE[untrustedReason] ?? 'did not pass its check'}. Reinstall COS Control, then install Parakeet.`
+            : 'Parakeet needs the speech tool that comes with COS Control. Update COS Control, then install Parakeet here.'
+          : cli.known === null
+            ? 'Checking this Mac for the speech tool.'
             : live
               ? 'Install after the live recording is saved.'
-              : 'About 654 MB. Installs the pinned model and checks every file.'
+              : 'Install Parakeet (654 MB). It downloads the pinned model, checks every file and runs offline. Dictation uses Whisper until it is ready.'
   return {
     installed: installed.installed,
     installable,
+    cli: { trust: installed.installed ? installedCliTrust() : cli.trust, reason: untrustedReason },
     version: PARAKEET_VERSION_LABEL,
     bytes: installed.installed ? installed.bytes : progress.bytesDone,
     progress: { ...progress, state: installed.installed && !running ? 'installed' : progress.state },
@@ -139,7 +170,8 @@ export const WARM_RETRY_MS = 120_000
 export function ensurePreviewWarm(now = Date.now()): 'started' | 'skipped' | 'deferred' {
   const settings = readSttSettings()
   // 6.73.0: a Parakeet HQ model also warms, because dictation final text uses it only warm.
-  const wanted = settings.preview === 'parakeet' || settings.hq === 'parakeet-ultra'
+  // 6.74.0: so does Mac dictation on auto or parakeet-ultra (the default is auto).
+  const wanted = settings.preview === 'parakeet' || settings.hq === 'parakeet-ultra' || settings.dictation !== 'whisper'
   if (!wanted || !parakeetInstalled().installed) return 'skipped'
   const w = parakeetWarmState(PREVIEW_PARAKEET_MODEL)
   if (w.state === 'warm' || w.state === 'warming') return 'skipped'

package/server/lib/stt-settings.ts

@@ -19,12 +19,15 @@ 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
+/** 6.74.0: the engine for Mac dictation (COS Control). It does not follow the Preview model. */
+export const DICTATION_IDS = ['auto', 'parakeet-ultra', 'whisper'] 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 type DesktopDictationId = typeof DICTATION_IDS[number]
 
 export interface SttSettings {
   preview: PreviewId
@@ -33,6 +36,8 @@ export interface SttSettings {
   resolver: boolean
   frontEnd: FrontEndId
   quietGate: QuietGateId
+  /** 6.74.0: Mac dictation engine. auto = Parakeet Ultra when installed and warm, else local Whisper. */
+  dictation: DesktopDictationId
 }
 
 /** Items 1 to 3 on. Second opinion off and the resolver off: on the shipped
@@ -47,6 +52,9 @@ export const DEFAULT_STT_SETTINGS: Readonly<SttSettings> = Object.freeze({
   resolver: false,
   frontEnd: 'highpass',
   quietGate: 'silero',
+  // Every install before 6.74.0 has no key and reads as auto, including Macs that
+  // chose Parakeet: auto keeps Parakeet wherever it is installed and warm.
+  dictation: 'auto',
 })
 
 export const STT_SETTINGS_FILE = 'stt-settings.json'
@@ -66,6 +74,7 @@ export function normalizeStoredSettings(raw: unknown): SttSettings {
     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),
+    dictation: pick(DICTATION_IDS, o.dictation, DEFAULT_STT_SETTINGS.dictation),
   }
 }
 
@@ -209,7 +218,7 @@ export class SttSettingsError extends Error {
   constructor(message: string) { super(message); this.name = 'SttSettingsError' }
 }
 
-const KEYS = ['preview', 'hq', 'secondOpinion', 'resolver', 'frontEnd', 'quietGate'] as const
+const KEYS = ['preview', 'hq', 'secondOpinion', 'resolver', 'frontEnd', 'quietGate', 'dictation'] as const
 
 /**
  * Apply a partial PUT. Throws SttSettingsError with a plain sentence for an
@@ -238,12 +247,14 @@ export function applySettingsPatch(current: SttSettings, body: unknown, c: SttCa
   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')
+  const dictation = choose('dictation', DICTATION_IDS, desktopDictationOptions(c), 'Dictation engine')
   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 (dictation) next.dictation = dictation
   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.')
@@ -370,6 +381,75 @@ export const DICTATION_REASON_TEXT: Record<string, string> = {
   dictation_disabled_by_env: 'Dictation is held on Whisper on this server (COS_DICTATION_FOLLOWS_STT=0).',
 }
 
+// ── Mac dictation (6.74.0) ────────────────────────────────────────────────────
+//
+// COS Control's dictation has its own setting and never follows the Preview model.
+// auto: Parakeet Ultra when installed, warm and its breaker closed, otherwise the
+// local Whisper live worker for that decode (and a warm-up starts). Never the cloud.
+// parakeet-ultra: Parakeet only, as 6.73.x did; when it cannot run the request fails.
+// whisper: local Whisper only.
+
+/** Whisper weights for the live worker are on this Mac. */
+export function desktopWhisperPresent(c: SttCapabilities): boolean {
+  return c.turboModel || c.liveLargeV3
+}
+
+export function desktopDictationOptions(c: SttCapabilities): SttOption[] {
+  const whisper = desktopWhisperPresent(c)
+  return [
+    { id: 'auto', label: 'Automatic', available: true, experimental: false,
+      note: 'Parakeet Ultra when it is installed and ready, otherwise Whisper on this Mac. Audio never leaves this Mac.' },
+    { id: 'parakeet-ultra', label: 'Parakeet Ultra', available: c.parakeetInstalled, experimental: false,
+      note: c.parakeetInstalled ? 'Parakeet only. While it warms up or is busy, dictation fails instead of using Whisper.' : 'Install Parakeet on this Mac first.' },
+    { id: 'whisper', label: 'Whisper', available: whisper, experimental: false,
+      note: whisper ? 'Whisper on this Mac only, with the names in your COS dictionary.' : 'Whisper weights are missing on this Mac.' },
+  ]
+}
+
+export interface DesktopDictationPlan extends DictationPlan {
+  setting: DesktopDictationId
+  /** Whisper may decode this request: auto and whisper, never parakeet-ultra. */
+  whisperAllowed: boolean
+}
+
+/** Pure: what a Mac dictation decode uses. The engine is chosen once, here. */
+export function desktopDictationPlan(slot: DictationSlot, settings: SttSettings, c: SttCapabilities): DesktopDictationPlan {
+  const setting = settings.dictation
+  const base = { slot, frontEnd: settings.frontEnd, setting, whisperAllowed: setting !== 'parakeet-ultra' }
+  const whisperKey = slot === 'final' ? 'final:large-v3' : `${slot}:turbo`
+  if (setting === 'whisper') return { ...base, engine: 'whisper', reason: null, key: whisperKey }
+  const reason = c.dictationDisabledByEnv ? 'dictation_disabled_by_env'
+    : !c.parakeetInstalled ? 'parakeet_not_installed'
+      : c.parakeetPreviewBreakerOpen ? 'parakeet_breaker_open'
+        : c.parakeetPreviewWarm ? null
+          : c.parakeetPreviewWarmFailed ? 'parakeet_warm_failed'
+            : 'parakeet_warming'
+  if (reason) return { ...base, engine: 'whisper', reason, key: whisperKey }
+  return { ...base, engine: 'parakeet-ultra', reason: null, key: slot === 'final' ? 'final:parakeet-ultra' : `${slot}:parakeet` }
+}
+
+const reasonText = (code: string) => REASON_TEXT[code] ?? DICTATION_REASON_TEXT[code] ?? code
+
+export function desktopDictationView(settings: SttSettings, c: SttCapabilities) {
+  const plan = desktopDictationPlan('fast', settings, c)
+  const effective: DictationEngine | 'none' = plan.engine === 'parakeet-ultra' ? 'parakeet-ultra'
+    : plan.whisperAllowed && desktopWhisperPresent(c) ? 'whisper' : 'none'
+  const code = plan.reason
+  const note = effective === 'parakeet-ultra' ? 'Mac dictation uses Parakeet Ultra on this Mac.'
+    : effective === 'whisper'
+      ? settings.dictation === 'auto' && code ? `Mac dictation uses Whisper on this Mac for now. ${reasonText(code)}` : 'Mac dictation uses Whisper on this Mac.'
+      : settings.dictation === 'parakeet-ultra' ? `Mac dictation waits for Parakeet.${code ? ` ${reasonText(code)}` : ''}`
+        : 'No dictation engine is ready on this Mac. Install Parakeet, or the Whisper weights.'
+  return {
+    selected: settings.dictation,
+    effective,
+    reason: code ? reasonText(code) : null,
+    reasonCode: code,
+    options: desktopDictationOptions(c),
+    note,
+  }
+}
+
 function dictationSlotView(plan: DictationPlan, follows: 'preview' | 'hq') {
   const code = plan.reason
   return { engine: plan.engine, follows, reason: code ? (REASON_TEXT[code] ?? DICTATION_REASON_TEXT[code] ?? code) : null, reasonCode: code }
@@ -381,7 +461,8 @@ export function dictationView(settings: SttSettings, c: SttCapabilities) {
   const final = dictationPlan('final', settings, c)
   const anyParakeet = settings.preview === 'parakeet' || settings.hq === 'parakeet-ultra'
   const name = (p: DictationPlan) => p.engine === 'parakeet-ultra' ? 'Parakeet Ultra' : 'Whisper'
-  const note = `Dictation follows these settings: the live preview and Fast mode use the Preview model (now ${name(preview)}), the final text uses the HQ model (now ${name(final)}). `
+  const note = `Glasses and phone dictation follow these settings: the live preview and Fast mode use the Preview model (now ${name(preview)}), the final text uses the HQ model (now ${name(final)}). `
+    + 'Mac dictation has its own engine setting. '
     + 'Dictation never runs the second opinion or the resolver, and the quiet gate never drops a spoken prompt.'
   return {
     preview: dictationSlotView(preview, 'preview'),
@@ -391,6 +472,8 @@ export function dictationView(settings: SttSettings, c: SttCapabilities) {
     quietGate: 'none' as const,
     secondOpinion: 'off' as const,
     note,
+    /** 6.74.0: COS Control's Mac dictation (POST /api/transcribe?requiredEngine=local). */
+    desktop: desktopDictationView(settings, c),
   }
 }
 
@@ -399,7 +482,9 @@ export interface ParakeetStatus {
   installable: boolean
   version: string
   bytes: number
-  progress: { state: string; bytesDone: number; bytesTotal: number; error: string | null; source?: unknown }
+  progress: { state: string; bytesDone: number; bytesTotal: number; error: string | null; errorCode?: string | null; source?: unknown }
+  /** 6.74.0: how the CLI is (or would be) trusted, and why COS Control's copy was refused. */
+  cli?: { trust: 'sha256' | 'developer-id' | null; reason: string | null }
   warm: { preview: string; error?: string; at?: string }
   preview?: { breaker: { open: boolean; retryAt: string | null; misses: number }; counters: Record<string, number> }
   note: string