@gotcos/glasses-server 6.73.14 → 6.75.0

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' }

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 */ }
     }