@gotcos/glasses-server 6.73.5 → 6.74.0

package/CHANGELOG.md

@@ -1,3 +1,86 @@
+## 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.
+- QA before release: the store matches a Mac session from the sidecar's 4 KB head before it opens any markdown, so a list of Mac rows no longer reads the store's G2 recordings (617 files, about 16 MB, on every Control poll, including `?day=` every 3 s during a hand-off); a `day` with no `month` reads only that month's folder. Store rows carry their start `time` ("HH:MM", from the Time line, else the Date line, else the filename), so a Mac recording sorts by its time among the same day's operations rows instead of at 00:00, where the 20-row list could cut it. A Mac recording whose session an operations row or a merged scribe already holds is left out of the day dots as it is of the rows, so an operations copy counts once.
+- Not changed: Mac recordings still skip the operations pipeline (search, vector and graph index, Work intake). That is a product decision, not this fix.
+- Work chat cleans the planner's `contextItemIDs` instead of refusing the plan: unknown ids drop, repeats keep once, anything that is not a list of strings sends every item, and so does a list none of whose ids Control supplied; an empty list sends the fixed three. The count of unknown ids is logged (`[work-chat]`), never the ids. One stray id used to discard a whole high-effort plan (QA 2026-10-15).
+- Pair with Control 0.5.313. Transcription-candidate and cue flags stay disabled. No public publication is implied.
+
+## 6.73.13 — Work chat picks each assignment's context (local candidate)
+
+- Work chat input accepts optional `items` ({id, kind, label, estTokens}; ids and estimates only, never contents; at most 40; your request, the task and COS instructions required). The planner returns `contextItemIDs` per assignment, a subset of the supplied ids; the fixed three are always added and Control's order is kept; omitted means every item. GET `/api/work/chat` advertises `contextItems: true` and `maxContextItems: 40`. The planner is asked for the smallest set each assignment needs.
+- Work chat's output budget rises from 4,086 to 4,946 tokens so three full selections fit (derived in lib/work-chat.ts).
+- Pair with Control 0.5.312 (Work Context Meter, Plan and send). Transcription-candidate and cue flags stay disabled. No public publication is implied.
+
+## 6.73.12 — Atomic dictionary edits and Work chat planner effort (local candidate)
+
+- Work chat plans at a chosen effort: `low`, `medium` or `high` (default `high`, Miles 2026-10-15). GET `/api/work/chat` advertises `efforts`; the answer reports the effort used. Anything else is a 400 before any model call. Higher effort raises cost per plan; still one call per Plan click.
+- Work chat now thinks at medium and high (6,000 and 16,000 thinking tokens) with an output budget derived from its largest valid plan (4,086 tokens) and a 180-second deadline. Before, every plan ran with thinking off and a 1,400-token cap that could cut a full plan into a 503. Lens gist and Meeting Ask keep exactly their old settings (1,400 / 0 / 45 s, low).
+
+- Add `POST /api/transcription-glossary/vocabulary/add` `{term}`, `/vocabulary/remove` `{term}` and `/correction/remove` `{heard}`. Each changes one item inside the same write chain as PUT and learn, so COS Control's Dictionary pane no longer reads the whole dictionary and writes it back (a Fix a word landing in between could be lost). Same limits as learn: 500 terms, 100 UTF-16 units, no URL, email or path in the vocabulary. Hand edits are not logged for undo.
+- Pair with Control 0.5.310. Older servers keep reading and adding corrections from Control; single-word edits, Fix a word and Undo need 6.73.12. Transcription-candidate and cue flags stay disabled. No public publication is implied.
+
+## 6.73.11 — Fix a word: the dictionary learns (local candidate)
+
+- Add `POST /api/transcription-glossary/correction` `{heard, written, source}`: learns ONE correction and adds the spelling to the vocabulary in one write, serialized with PUT. A case variant of an existing key is replaced, not duplicated. Same limits as PUT: 500 terms, 100 characters, no URL, email or path spellings (they would join the decoder prompt). `source` is `dictation`, `meeting`, `g2` or `manual`.
+- Add `GET /api/transcription-glossary/recent`: what COS learned, newest first, with source and time. The log lives in the data dir (`transcription-corrections.json`, last 200, atomic, 0600); the dictionary stays in `.cos-profile.json`.
+- Add `POST /api/transcription-glossary/correction/undo` `{id}`: reverts exactly that entry, puts back a replaced case variant, and removes the spelling only if no remaining correction writes it. Refuses with 409 when a newer entry owns the word or it was edited since.
+- Live, meeting and dictation transcription pick a learned word up on the next sentence (decoder and vocab-echo caches are cleared). Pair with Control 0.5.309. 6.73.10 is the Work chat candidate on its own branch. Transcription-candidate and cue flags stay disabled. No public publication is implied.
+
+## 6.73.10 — Choose the Work chat planner (local candidate)
+
+- Accept an optional `planner` (`sonnet` or `opus`) on `POST /api/work/chat` and run that Claude model, still tools-off. Anything else is a 400 before any model call. Clients that send none keep Sonnet. `GET /api/work/chat` now advertises `planners: ["sonnet","opus"]` and keeps `planner: "sonnet"` as the default; the answer's `model` names what ran. The choice selects the model only and never reaches the prompt.
+- Cost: still one model call per user action, serialized by the existing busy lock (a second request gets 409). Opus costs more per call than Sonnet; nothing new runs on a schedule.
+- Planning still never dispatches. Ships with Control 0.5.309, which reviews every planned assignment before anything is sent. Transcription-candidate and cue flags stay disabled. No public publication is implied.
+
+## 6.73.9 — Keep stalled Mac captures recoverable (local candidate)
+
+- Never auto-save or expire a Mac capture (`mac_<uuid>`). COS Control keeps every chunk on the Mac and delivers or recovers it. The 4 h stranded sweep posted the save without the server pin a Mac save requires, read the 400 as final and closed the session; boot recovery closed any session idle past 4 h the same way. A capture stalled at 51 of 1,200 chunks (2026-10-15) would have lost its server-side recovery at 20:12. Both paths now leave Mac captures open (`restoresAtBoot`, sweep guard).
+- Note for 6.73.6 to 6.73.8: the decision provider switch (Jev or SubQ) for Work search, session suggestions and completion checks, with authenticated `/api/decision-provider` and `/api/subq-key` routes, a private 0600 SubQ key file, and `COS_SUBQ_DAILY_TOKENS` (default 1M) capping each workflow's daily usage separately. SubQ sends the decision prompt to SubQ's API. Meeting intake (`work_intake.py`) stays on Jev.
+- Known limitation: in a saved Mac meeting's full-quality Parakeet pass, a window with no words over detected speech still abandons that pass; the meeting saves with its live transcript.
+- Pair with Control 0.5.307. Transcription-candidate and cue flags stay disabled. No public publication is implied.
+
+## 6.73.8 — Live Ask on Mac recordings (local candidate)
+
+- Accept Mac capture ids (`mac_<uuid>`, the id the Mac recording route issues) in live COS Ask, Ask history, files and orientation, and Work intake Ask evidence. Every Ask on a Mac recording failed with `invalid_session_id`; found in a live meeting 2026-10-15. One shared pattern in `lib/ask-session-id.ts`; traversal-shaped and upper-case ids stay refused.
+- Record Parakeet's no-words answer over detected speech on a Mac chunk as an empty chunk with a `[mac-asr]` warning, instead of a retryable 503. Replays of the same audio failed forever and froze every later chunk of a live meeting (2026-10-15, chunk 51). Real Parakeet failures stay retryable with no Whisper fallback; the saved meeting still re-transcribes the full audio with strict Parakeet.
+- Pair with Control 0.5.306. Transcription-candidate and cue flags stay disabled. No public publication is implied.
+
+## 6.73.7 — Strict local desktop dictation (local candidate)
+
+- Advertise the desktop dictation capability before microphone audio is transferred.
+- Honor an explicit Parakeet Ultra requirement through the existing COS dictionary and vocabulary pipeline; return a retryable error rather than substituting Whisper or cloud transcription.
+- Bound streamed desktop audio to two minutes of canonical PCM16 WAV data. Preserve legacy transcription behavior for callers without the engine requirement.
+- Pair with Control 0.5.303 for microphone dictation and shared Mac live meeting views. Retain the recording/onboarding/SubQ changes from 6.73.6 and keep transcription-candidate/cue flags disabled. No public publication is implied.
+
+## 6.73.6 — Manual Mac recording transport (local candidate)
+
+- Register selected-app Mac system-audio capture with immutable source identity and high-confidence speaker policy before admitting audio.
+- Persist canonical PCM chunk receipts, exact timing and capture provenance through retry, save and meeting context. Reject missing chunks, conflicting retries and source substitution.
+- Keep Mac playback out of automatic G2/Fireflies merges and voice training. Glasses are optional for the matched Control 0.5.301 pilot.
+- Preserve transcription settings and disabled transcription-candidate/cue flags. Signed-host capture and permission acceptance remain local installation gates; this entry does not indicate public availability.
+
 ## 6.73.5 — Tasks from saved meetings (local candidate)
 
 - Add authenticated, bounded creation of a task and its exact source meeting in one canonical locked write.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gotcos/glasses-server",
-  "version": "6.73.5",
+  "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/index.ts

@@ -148,6 +148,8 @@ import { createWorkReviewsRouter } from './routes/work-reviews.js'
 import { createWorkBoardRouter } from './routes/work-board.js'
 import { createWorkIntakeRouter } from './routes/work-intake.js'
 import { createWorkHandoffRequestsRouter } from './routes/work-handoff-requests.js'
+import { createSubqKeyRouter } from './routes/subq-key.js'
+import { createDecisionProviderRouter } from './routes/decision-provider.js'
 import { createJevRouter } from './routes/jev.js'
 import { createWorkChatRouter } from './routes/work-chat.js'
 import { createWorkSearchRouter } from './routes/work-search.js'
@@ -384,6 +386,7 @@ app.use('/api', (req, res, next) => {
     || req.path === '/diagnostics/provider-proof'
     || req.path === '/transcribe'
     || req.path.startsWith('/transcribe-stream')
+    || req.path.startsWith('/mac-recording/')
     || req.path === '/meeting/save'
     // The import run answers 202 and keeps working. It takes its own
     // maintenance lease per page and checks admissions itself, so the global
@@ -798,6 +801,8 @@ app.use('/api', createWorkIntakeRouter({ store: workIntakeStore }))
 // (6.57.1), and the Work completion check (6.58.0).
 app.use('/api', createJevRouter(workReviewRuntime ? { review: async id => workReviewRuntime.peek(id) } : {}))
 // Work search by meaning (6.65.0, Control 0.5.259): one Jev Choice over the board's cards, with its own cap, switch and breaker.
+app.use('/api', createDecisionProviderRouter())
+app.use('/api', createSubqKeyRouter())
 app.use('/api', createWorkSearchRouter())
 app.use('/api', createWorkChatRouter())
 app.use('/api', queryRouter)

package/server/lib/ask-session-id.ts

@@ -0,0 +1,5 @@
+// Which recordings may open live Ask, its history and Work evidence. 6.73.8: a Mac capture
+// (mac_<uuid>, lib/mac-recording.ts MAC_CAPTURE_ID) uses the same Ask as a G2 meeting; before this
+// every Mac request and saved-question read failed with invalid_session_id.
+export const MAC_ASK_SESSION = /^mac_[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/
+export const ASK_SESSION = /^(?:meeting_[A-Za-z0-9_-]{1,89}|mac_[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})$/

package/server/lib/decision-provider.ts

@@ -0,0 +1,163 @@
+/** Explicit classifier routing. No retry or cross-provider fallback; generative engines do not use this seam. */
+import { lstatSync, mkdirSync, readFileSync } from 'node:fs'
+import { dirname } from 'node:path'
+import { JevClient, JevError, type JevAnswers } from './jev.js'
+import { dataPath } from './data-dir.js'
+import { durableAtomicWriteFileSync } from './atomic-fs.js'
+import { redactSecretText } from './activity-preview.js'
+import { secureExistingPrivateFile } from './secure-user-config.js'
+
+import { resolveSubqKey, SUBQ_MODEL } from './subq-key.js'
+export { SUBQ_MODEL } from './subq-key.js'
+import { resolveDecisionSelection, type DecisionProvider, type DecisionUseCase } from './decision-settings.js'
+export type { DecisionProvider, DecisionUseCase } from './decision-settings.js'
+export interface DecisionImage { mediaType: 'image/png' | 'image/jpeg' | 'image/webp'; base64: string }
+export interface DecisionOptions { signal?: AbortSignal; images?: DecisionImage[] }
+export interface DecisionClient { readonly provider?: DecisionProvider; snapshot?: () => DecisionClient; ask(state: unknown, questions: Record<string, unknown>, estimate: number, options?: DecisionOptions): Promise<JevAnswers> }
+export class DecisionProviderError extends Error {
+  constructor(readonly code: 'decision_invalid_provider' | 'decision_not_configured' | 'decision_cap_reached' | 'decision_breaker_open' |
+    'decision_key_rejected' | 'decision_credits_required' | 'decision_rate_limited' | 'decision_request_rejected' | 'decision_unavailable' |
+    'decision_bad_answer' | 'decision_cancelled' | 'decision_images_unsupported' | 'decision_usage_unavailable') { super(code) }
+}
+export const SUBQ_ENDPOINT = 'https://api.subq.ai/v1/systemone'
+export const SUBQ_LIMITS = { timeoutMs: 20_000, dailyTokens: 1_000_000, breakerFailures: 3, breakerMs: 3_600_000, maxBodyBytes: 13 * 1024 * 1024 } as const
+
+/** No key probing, and no unknown value silently treated as Jev. Per-use-case settings override the global switch. */
+export function selectedDecisionProvider(useCase: DecisionUseCase, env: NodeJS.ProcessEnv = process.env): DecisionProvider {
+  try { return resolveDecisionSelection(useCase, env).provider } catch { throw new DecisionProviderError('decision_invalid_provider') }
+}
+const isRecord = (v: unknown): v is Record<string, unknown> => !!v && typeof v === 'object' && !Array.isArray(v)
+const probability = (v: unknown): v is number => typeof v === 'number' && Number.isFinite(v) && v >= 0 && v <= 1
+function clean(value: unknown): unknown {
+  if (typeof value === 'string') return redactSecretText(value).replace(/[A-Z0-9._%+-]+@[A-Z0-9.-]+\.[A-Z]{2,}/gi, '[email]')
+    .replace(/\b\d{3}[-. ]\d{3}[-. ]\d{4}\b/g, '[phone]')
+  if (Array.isArray(value)) return value.map(clean)
+  if (isRecord(value)) return Object.fromEntries(Object.entries(value).map(([key, v]) => [String(clean(key)), clean(v)]))
+  return value
+}
+/** Validate locally. Image bytes are never logged, persisted, fetched by URL, or inferred from a user's screen. */
+function requestBody(state: unknown, questions: Record<string, unknown>, images: DecisionImage[] = []): string {
+  const entries = Object.entries(questions)
+  if (!entries.length || entries.length > 16 || entries.some(([k, q]) => !k || k.length > 100 || !isRecord(q) || typeof q.instructions !== 'string' ||
+    !['noul', 'choice', 'score'].includes(String(q.type)) || (q.type === 'choice' && (!isRecord(q.criteria) || Object.keys(q.criteria).length < 2 || Object.keys(q.criteria).length > 255)) ||
+    (q.type === 'score' && (!Array.isArray(q.criteria) || q.criteria.length < 2 || q.criteria.length > 10)))) throw new DecisionProviderError('decision_request_rejected')
+  let total = 0
+  if (images.length > 4) throw new DecisionProviderError('decision_request_rejected')
+  for (const image of images) {
+    if (!['image/png', 'image/jpeg', 'image/webp'].includes(image.mediaType) || !/^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/.test(image.base64)) throw new DecisionProviderError('decision_request_rejected')
+    const bytes = Buffer.from(image.base64, 'base64'); total += bytes.length
+    const valid = image.mediaType === 'image/png' ? bytes.subarray(0, 8).equals(Buffer.from('89504e470d0a1a0a', 'hex')) :
+      image.mediaType === 'image/jpeg' ? bytes[0] === 255 && bytes[1] === 216 && bytes[2] === 255 : bytes.toString('ascii', 0, 4) === 'RIFF' && bytes.toString('ascii', 8, 12) === 'WEBP'
+    if (!valid || bytes.length > 4 * 1024 * 1024 || total > 8 * 1024 * 1024) throw new DecisionProviderError('decision_request_rejected')
+  }
+  const body = JSON.stringify({ model: SUBQ_MODEL, state: clean(state), questions: clean(questions), ...(images.length ? { images } : {}) })
+  if (Buffer.byteLength(body) > SUBQ_LIMITS.maxBodyBytes) throw new DecisionProviderError('decision_request_rejected')
+  return body
+}
+
+/** Strict schema at the provider boundary, before any workflow threshold can turn it into advice. */
+export function validateDecisionAnswers(raw: unknown, questions: Record<string, unknown>): JevAnswers['answers'] {
+  if (!isRecord(raw) || Object.keys(raw).length !== Object.keys(questions).length) throw new DecisionProviderError('decision_bad_answer')
+  for (const [name, spec] of Object.entries(questions)) {
+    const q = spec as Record<string, unknown>, a = raw[name]
+    if (!isRecord(a) || a.type !== q.type) throw new DecisionProviderError('decision_bad_answer')
+    if (q.type === 'noul') { if (!probability(a.noul)) throw new DecisionProviderError('decision_bad_answer'); continue }
+    const criteria = q.criteria as Record<string, unknown> | unknown[]
+    const labels = Object.keys(criteria), probs = a.probabilities
+    if (!isRecord(probs) || Object.keys(probs).length !== labels.length || labels.some(k => !probability(probs[k])) ||
+      Math.abs(Object.values(probs).reduce<number>((sum, p) => sum + Number(p), 0) - 1) > 0.02 || !probability(a.confidence)) throw new DecisionProviderError('decision_bad_answer')
+    if (q.type === 'choice' && (typeof a.choice !== 'string' || !labels.includes(a.choice))) throw new DecisionProviderError('decision_bad_answer')
+    if (q.type === 'score' && (typeof a.score !== 'number' || !Number.isFinite(a.score) || a.score < 0 || a.score > labels.length - 1 || !isRecord(a.legend) || labels.some(k => !(k in (a.legend as Record<string, unknown>))))) throw new DecisionProviderError('decision_bad_answer')
+  }
+  return raw as JevAnswers['answers']
+}
+
+export class SubqDecisionClient implements DecisionClient {
+  readonly provider = 'subq' as const
+  private failures = 0
+  private breakerUntil = 0
+  private reserved = 0
+  constructor(private readonly fetchImpl: typeof fetch = fetch, private readonly now: () => Date = () => new Date(),
+    private readonly usageFile = dataPath('subq-decisions-usage.json'), private readonly key = () => resolveSubqKey()?.key,
+    private readonly cap = () => { const n = Number(process.env.COS_SUBQ_DAILY_TOKENS); return Number.isFinite(n) && n > 0 ? Math.floor(n) : SUBQ_LIMITS.dailyTokens },
+    private readonly timeoutMs: number = SUBQ_LIMITS.timeoutMs) {}
+  resetForNewKey(): void { this.failures = 0; this.breakerUntil = 0 }
+  private ledger(): Record<string, number> {
+    try {
+      const stat = lstatSync(this.usageFile)
+      if (stat.isSymbolicLink() || !stat.isFile()) throw new Error('unsafe')
+    } catch (e) {
+      if (e && typeof e === 'object' && 'code' in e && e.code === 'ENOENT') return {}
+      throw new DecisionProviderError('decision_usage_unavailable')
+    }
+    try {
+      secureExistingPrivateFile(this.usageFile)
+      const value: unknown = JSON.parse(readFileSync(this.usageFile, 'utf8'))
+      if (!isRecord(value) || Object.entries(value).some(([day, count]) => !/^\d{4}-\d{2}-\d{2}$/.test(day) || typeof count !== 'number' || !Number.isFinite(count) || count < 0 || count > Number.MAX_SAFE_INTEGER)) throw new Error('invalid')
+      return value as Record<string, number>
+    } catch { throw new DecisionProviderError('decision_usage_unavailable') }
+  }
+  private day(): string { return this.now().toISOString().slice(0, 10) }
+  private record(tokens: number): void {
+    try {
+      const ledger = this.ledger(); ledger[this.day()] = (ledger[this.day()] ?? 0) + tokens
+      mkdirSync(dirname(this.usageFile), { recursive: true, mode: 0o700 })
+      durableAtomicWriteFileSync(this.usageFile, JSON.stringify(ledger) + '\n', { mode: 0o600 })
+    } catch { throw new DecisionProviderError('decision_usage_unavailable') }
+  }
+  private fail(code: DecisionProviderError['code'], breaker = false): never {
+    if (breaker && ++this.failures >= SUBQ_LIMITS.breakerFailures) { this.breakerUntil = this.now().getTime() + SUBQ_LIMITS.breakerMs; this.failures = 0 }
+    throw new DecisionProviderError(code)
+  }
+  async ask(state: unknown, questions: Record<string, unknown>, _estimate: number, options: DecisionOptions = {}): Promise<JevAnswers> {
+    if (options.signal?.aborted) return this.fail('decision_cancelled')
+    const key = this.key(); if (!key) return this.fail('decision_not_configured')
+    if (this.breakerUntil > this.now().getTime()) return this.fail('decision_breaker_open')
+    const body = requestBody(state, questions, options.images)
+    // Reserve a conservative byte-based estimate, including encoded images, before concurrent requests can enter.
+    const estimate = Buffer.byteLength(body) + 1
+    if ((Number(this.ledger()[this.day()]) || 0) + this.reserved + estimate > this.cap()) return this.fail('decision_cap_reached')
+    this.reserved += estimate
+    try {
+      let res: Response
+      try { res = await this.fetchImpl(SUBQ_ENDPOINT, { method: 'POST', redirect: 'error', headers: { Authorization: `Bearer ${key}`, 'Content-Type': 'application/json' },
+        body, signal: AbortSignal.any([AbortSignal.timeout(this.timeoutMs), ...(options.signal ? [options.signal] : [])]) }) }
+      catch { this.record(estimate); return this.fail(options.signal?.aborted ? 'decision_cancelled' : 'decision_unavailable', !options.signal?.aborted) }
+      if (res.status === 401 || res.status === 403) return this.fail('decision_key_rejected')
+      if (res.status === 402) return this.fail('decision_credits_required')
+      if (res.status === 429) return this.fail('decision_rate_limited')
+      if ([400, 413, 422].includes(res.status)) return this.fail('decision_request_rejected')
+      if (!res.ok) return this.fail('decision_unavailable', true)
+      // Count conservative usage even when a successful response is unreadable. No raw provider error is echoed.
+      let raw: unknown
+      try { raw = await res.json() } catch { this.record(estimate); return this.fail('decision_bad_answer', true) }
+      const used = isRecord(raw) && isRecord(raw.usage) && typeof raw.usage.input_tokens === 'number' && Number.isFinite(raw.usage.input_tokens) && raw.usage.input_tokens > 0 ? raw.usage.input_tokens : estimate
+      this.record(used)
+      if (!isRecord(raw) || raw.model !== SUBQ_MODEL) return this.fail('decision_bad_answer', true)
+      let answers: JevAnswers['answers']
+      try { answers = validateDecisionAnswers(raw.answers, questions) } catch { return this.fail('decision_bad_answer', true) }
+      this.failures = 0
+      return { provider: 'subq', answers, model: SUBQ_MODEL, inputTokens: used }
+    } finally { this.reserved -= estimate }
+  }
+}
+
+const configuredSubqClients = new Set<SubqDecisionClient>()
+export function resetSubqDecisionClients(): void { configuredSubqClients.forEach(client => client.resetForNewKey()) }
+/** Snapshot selection per workflow request. Separate clients and cache identities prevent stale cross-provider answers. */
+export function createDecisionClient(useCase: DecisionUseCase, jev: Pick<JevClient, 'ask'> = new JevClient(), env: NodeJS.ProcessEnv = process.env): DecisionClient {
+  const clients: Partial<Record<DecisionProvider, DecisionClient>> = {}
+  const snapshot = (): DecisionClient => {
+    const selected = selectedDecisionProvider(useCase, env)
+    if (!clients[selected]) clients[selected] = selected === 'subq' ? new SubqDecisionClient(fetch, () => new Date(), dataPath(`subq-${useCase}-usage.json`)) : {
+      provider: 'jev', async ask(state, questions, estimate, options) {
+        if (options?.images?.length) throw new DecisionProviderError('decision_images_unsupported')
+        return { ...await jev.ask(state, questions, estimate, options), provider: 'jev' }
+      },
+    }
+    if (selected === 'subq') configuredSubqClients.add(clients[selected] as SubqDecisionClient)
+    return clients[selected]!
+  }
+  return { snapshot, ask: (state, questions, estimate, options) => snapshot().ask(state, questions, estimate, options) }
+}
+export function isDecisionFailure(error: unknown): error is JevError | DecisionProviderError { return error instanceof JevError || error instanceof DecisionProviderError }

package/server/lib/decision-settings.ts

@@ -0,0 +1,72 @@
+/** Private, durable classifier selection. No key storage or account/network changes. */
+import { createHash } from 'node:crypto'
+import { lstatSync, readFileSync } from 'node:fs'
+import { dirname } from 'node:path'
+import { dataPath } from './data-dir.js'
+import { durableAtomicWriteFileSync } from './atomic-fs.js'
+import { secureExistingPrivateFile, securePrivateDirectory } from './secure-user-config.js'
+
+export type DecisionProvider = 'jev' | 'subq'
+export const DECISION_WORKFLOWS = ['session', 'completion', 'search'] as const
+export type DecisionUseCase = typeof DECISION_WORKFLOWS[number]
+export interface DecisionSettings { schema: 1; provider?: DecisionProvider; overrides: Partial<Record<DecisionUseCase, DecisionProvider>> }
+export class DecisionSettingsError extends Error {
+  constructor(readonly code: 'invalid_decision_settings' | 'decision_settings_unavailable' | 'decision_invalid_provider' | 'decision_settings_conflict') { super(code) }
+}
+const record = (v: unknown): v is Record<string, unknown> => !!v && typeof v === 'object' && !Array.isArray(v)
+const provider = (v: unknown): v is DecisionProvider => v === 'jev' || v === 'subq'
+const settingsFile = () => dataPath('decision-provider.json')
+export function readDecisionSettings(file = settingsFile()): DecisionSettings {
+  // Only an absent directory entry means defaults. A dangling symlink or a file
+  // disappearing after this check must not silently change the selected provider.
+  try {
+    const stat = lstatSync(file)
+    if (stat.isSymbolicLink() || !stat.isFile()) throw new Error('unsafe')
+  } catch (e) {
+    if (e && typeof e === 'object' && 'code' in e && e.code === 'ENOENT') return { schema: 1, overrides: {} }
+    throw new DecisionSettingsError('decision_settings_unavailable')
+  }
+  try {
+    secureExistingPrivateFile(file)
+    const value = JSON.parse(readFileSync(file, 'utf8'))
+    if (!record(value) || value.schema !== 1 || !record(value.overrides) || Object.keys(value).some(k => !['schema','provider','overrides'].includes(k)) ||
+      (value.provider !== undefined && !provider(value.provider)) || Object.entries(value.overrides).some(([key,v]) => !DECISION_WORKFLOWS.includes(key as DecisionUseCase) || !provider(v))) throw new Error('invalid')
+    return value as unknown as DecisionSettings
+  } catch {
+    throw new DecisionSettingsError('decision_settings_unavailable')
+  }
+}
+export function decisionSettingsRevision(settings: DecisionSettings): string {
+  return createHash('sha256').update(JSON.stringify([settings.provider ?? null, ...DECISION_WORKFLOWS.map(w => settings.overrides[w] ?? null)])).digest('hex')
+}
+export function patchDecisionSettings(current: DecisionSettings, raw: unknown): DecisionSettings {
+  if (!record(raw) || !Object.keys(raw).length || Object.keys(raw).some(k => !['provider','overrides','expectedRevision'].includes(k)) || typeof raw.expectedRevision !== 'string' || !/^[a-f0-9]{64}$/.test(raw.expectedRevision) || (!('provider' in raw) && !('overrides' in raw)) ||
+    ('provider' in raw && raw.provider !== null && !provider(raw.provider)) ||
+    ('overrides' in raw && (!record(raw.overrides) || !Object.keys(raw.overrides).length || Object.entries(raw.overrides).some(([k,v]) => !DECISION_WORKFLOWS.includes(k as DecisionUseCase) || (v !== null && !provider(v)))))) {
+    throw new DecisionSettingsError('invalid_decision_settings')
+  }
+  if (raw.expectedRevision !== decisionSettingsRevision(current)) throw new DecisionSettingsError('decision_settings_conflict')
+  const next: DecisionSettings = { ...current, overrides: { ...current.overrides } }
+  if ('provider' in raw) { if (raw.provider === null) delete next.provider; else next.provider = raw.provider as DecisionProvider }
+  if (record(raw.overrides)) for (const [key,value] of Object.entries(raw.overrides)) {
+    if (value === null) delete next.overrides[key as DecisionUseCase]; else next.overrides[key as DecisionUseCase] = value as DecisionProvider
+  }
+  return next
+}
+export function writeDecisionSettings(next: DecisionSettings, file = settingsFile()): void {
+  securePrivateDirectory(dirname(file)); secureExistingPrivateFile(file)
+  durableAtomicWriteFileSync(file, JSON.stringify(next) + '\n', { mode: 0o600 })
+}
+export function resolveDecisionSelection(useCase: DecisionUseCase, env: NodeJS.ProcessEnv = process.env, settings = readDecisionSettings()): { provider: DecisionProvider; source: 'config' | 'env' | 'default' } {
+  const workflowEnv = env[`COS_DECISION_PROVIDER_${useCase.toUpperCase()}`]
+  const choice = settings.overrides[useCase] ?? workflowEnv ?? settings.provider ?? env.COS_DECISION_PROVIDER ?? 'jev'
+  const selected = choice.trim().toLowerCase()
+  if (!provider(selected)) throw new DecisionSettingsError('decision_invalid_provider')
+  return { provider: selected, source: settings.overrides[useCase] !== undefined ? 'config' : workflowEnv !== undefined ? 'env' : settings.provider !== undefined ? 'config' : env.COS_DECISION_PROVIDER !== undefined ? 'env' : 'default' }
+}
+export function decisionSettingsView(settings: DecisionSettings, configured: Record<DecisionProvider, boolean>, env: NodeJS.ProcessEnv = process.env) {
+  const global = resolveDecisionSelection('session', { COS_DECISION_PROVIDER: env.COS_DECISION_PROVIDER }, { schema: 1, provider: settings.provider, overrides: {} })
+  const selections = Object.fromEntries(DECISION_WORKFLOWS.map(w => [w, resolveDecisionSelection(w, env, settings)])) as Record<DecisionUseCase, ReturnType<typeof resolveDecisionSelection>>
+  return { schema: 1 as const, revision: decisionSettingsRevision(settings), provider: global.provider, overrides: settings.overrides, effective: Object.fromEntries(DECISION_WORKFLOWS.map(w => [w,selections[w].provider])),
+    sources: Object.fromEntries(DECISION_WORKFLOWS.map(w => [w,selections[w].source])), configured, saved: { provider: settings.provider ?? null, overrides: settings.overrides } }
+}

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) }
+  }
+}